uimaj-2.2.1-incubating/uimaj-tools/src/main/java/org/apache/uima/tools/pear/merger/PMUimaAgent.java - uima-uimaj - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License 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.
  */

 package org.apache.uima.tools.pear.merger;

 import java.io.File;
 import java.io.FileWriter;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.util.ArrayList;
 import java.util.Enumeration;
 import java.util.Hashtable;
 import java.util.Iterator;
 import java.util.Map;

 import org.apache.uima.ResourceSpecifierFactory;
 import org.apache.uima.UIMAFramework;
 import org.apache.uima.UIMA_IllegalStateException;
 import org.apache.uima.analysis_engine.AnalysisEngineDescription;
 import org.apache.uima.analysis_engine.TypeOrFeature;
 import org.apache.uima.analysis_engine.metadata.AnalysisEngineMetaData;
 import org.apache.uima.analysis_engine.metadata.FixedFlow;
 import org.apache.uima.collection.CasConsumerDescription;
 import org.apache.uima.pear.tools.InstallationDescriptor;
 import org.apache.uima.pear.util.StringUtil;
 import org.apache.uima.resource.ResourceSpecifier;
 import org.apache.uima.resource.metadata.Capability;
 import org.apache.uima.resource.metadata.Import;
 import org.apache.uima.resource.metadata.OperationalProperties;
 import org.apache.uima.resource.metadata.ProcessingResourceMetaData;
 import org.apache.uima.util.InvalidXMLException;
 import org.apache.uima.util.XMLInputSource;
 import org.apache.uima.util.XMLParser;
 import org.apache.uima.util.XMLizable;
 import org.xml.sax.SAXException;

 /**
  * The <code>PMUimaAgent</code> class implements UIMA-based utility methods utilized by the
  * <code>{@link PMController}</code> class. The class allows generating analysis engine descriptor
  * for output aggregate AE based on the specified input descriptors.
  */

 public class PMUimaAgent {
   /**
    * Creates UIMA aggregate analysis engine description object, based on given aggregate component name
    * (ID), aggregate root directory and array of delegate installation descriptors. Returns the UIMA
    * aggregate analysis engine description object.
    *
    * @param aggCompName
    *          The given aggregate component name (ID).
    * @param aggRootDir
    *          The given aggregate root directory.
    * @param dlgInstDescs
    *          The given array of delegate installation descriptors.
    * @return The UIMA aggregate analysis engine description object.
    */
   static AnalysisEngineDescription createAggregateDescription(String aggCompName, File aggRootDir,
           InstallationDescriptor[] dlgInstDescs) {
     AnalysisEngineDescription aggDescription = null;
     int lastInputNo = 0;
     try {
       // get UIMA resource specifier factory
       ResourceSpecifierFactory rsFactory = UIMAFramework.getResourceSpecifierFactory();
       // create aggregate AE description
       aggDescription = rsFactory.createAnalysisEngineDescription();
       aggDescription.setPrimitive(false);
       // get Map of delegate specifiers with imports
       Map delegatesMap = aggDescription.getDelegateAnalysisEngineSpecifiersWithImports();
       // add delegate imports to the Map
       for (int i = 0; i < dlgInstDescs.length; i++) {
         // get delegate component attributes
         InstallationDescriptor dlgInsD = dlgInstDescs[i];
         String dlgName = dlgInsD.getMainComponentId();
         String dlgDescPath = dlgInsD.getMainComponentDesc();
         // create Import for delegate component
         Import dlgImport = rsFactory.createImport();
         // set relative delegate descriptor location
         String dlgDescRelPath = dlgDescPath.replaceAll(PMControllerHelper.MAIN_ROOT_REGEX,
                 StringUtil.toRegExpReplacement(".."));
         dlgImport.setLocation(dlgDescRelPath);
         // add delegate Import to the Map
         delegatesMap.put(dlgName, dlgImport);
       }
       // get AE metadata
       AnalysisEngineMetaData aggMetadata = aggDescription.getAnalysisEngineMetaData();
       // set AE name and textual description
       aggMetadata.setName(aggCompName);
       aggMetadata.setDescription("Merged aggregate component" + "(" + PMController.PEAR_MERGER
               + ")");
       // set fixed flow constraints
       FixedFlow aggFixedFlow = rsFactory.createFixedFlow();
       String[] aggFlowSpecs = new String[dlgInstDescs.length];
       for (int i = 0; i < dlgInstDescs.length; i++)
         aggFlowSpecs[i] = dlgInstDescs[i].getMainComponentId();
       aggFixedFlow.setFixedFlow(aggFlowSpecs);
       aggMetadata.setFlowConstraints(aggFixedFlow);
       // collect capabilities & check operational props of delegates
       ArrayList allCapabilities = new ArrayList();
       boolean isMultipleDeploymentAllowed = true;
       boolean modifiesCas = false;
       for (int i = 0; i < dlgInstDescs.length; i++) {
         lastInputNo = i + 1;
         ResourceSpecifier dlgSpecifier = retrieveDelegateSpecifier(aggRootDir, dlgInstDescs[i]);
         if (dlgSpecifier instanceof AnalysisEngineDescription) {
           // get AE metadata
           AnalysisEngineMetaData dlgAeMetadata = ((AnalysisEngineDescription) dlgSpecifier)
                   .getAnalysisEngineMetaData();
           // collect AE capabilities
           Capability[] dlgCapabilities = dlgAeMetadata.getCapabilities();
           if (dlgCapabilities != null)
             for (int n = 0; n < dlgCapabilities.length; n++)
               allCapabilities.add(dlgCapabilities[n]);
           // check operational properties
           OperationalProperties dlgOperProps = dlgAeMetadata.getOperationalProperties();
           if (dlgOperProps != null) {
             if (!dlgOperProps.isMultipleDeploymentAllowed())
               isMultipleDeploymentAllowed = false;
             if (dlgOperProps.getModifiesCas())
               modifiesCas = true;
           } else
             // by default, AE modifies CAS
             modifiesCas = true;
         } else if (dlgSpecifier instanceof CasConsumerDescription) {
           // get CC metadata
           ProcessingResourceMetaData dlgCcMetadata = ((CasConsumerDescription) dlgSpecifier)
                   .getCasConsumerMetaData();
           // collect CC capabilities
           Capability[] dlgCapabilities = dlgCcMetadata.getCapabilities();
           if (dlgCapabilities != null)
             for (int n = 0; n < dlgCapabilities.length; n++)
               allCapabilities.add(dlgCapabilities[n]);
           // check operational properties
           OperationalProperties dlgOperProps = dlgCcMetadata.getOperationalProperties();
           if (dlgOperProps != null) {
             if (!dlgOperProps.isMultipleDeploymentAllowed())
               isMultipleDeploymentAllowed = false;
           }
         } else
           // other categories (CR, CI) are not allowed
           throw new IllegalArgumentException("unsupported input component");
       }
       // merge capabilities, excluding duplicates
       Capability[] mergedCapabilities = mergeCapabilities(allCapabilities, rsFactory);
       // set aggregate capabilities
       aggMetadata.setCapabilities(mergedCapabilities);
       // set aggregate operational properties
       OperationalProperties aggOperProps = aggMetadata.getOperationalProperties();
       if (aggOperProps != null) {
         aggOperProps.setMultipleDeploymentAllowed(isMultipleDeploymentAllowed);
         aggOperProps.setModifiesCas(modifiesCas);
       }
     } catch (IllegalArgumentException exc) {
       PMController.logErrorMessage("Invalid input component # " + lastInputNo);
       PMController.logErrorMessage("IllegalArgumentException: " + exc.getMessage());
       aggDescription = null;
     } catch (Throwable err) {
       if (lastInputNo > 0)
         PMController.logErrorMessage("Error in input component # " + lastInputNo);
       PMController.logErrorMessage(err.toString());
       aggDescription = null;
     } finally {
     }
     return aggDescription;
   }

   /**
    * Merges source <code>Capability<code> objects specified in a given
    * <code>ArrayList</code>, creating one <code>Capability<code> object
    * that contains all non-duplicated inputs and outputs of the source
    * <code>Capability<code> objects. Returns an array of
    * <code>Capability<code> objects, containing the merged object.
    *
    * @param allCapabilities The given <code>ArrayList</code> of the source
    * <code>Capability<code> objects.
    * @param rsFactory The <code>ResourceSpecifierFactory</code> object
    * used to create new <code>Capability<code> object.
    * @return Array of <code>Capability<code> objects, containing the merged
    * object.
    */
   private static Capability[] mergeCapabilities(ArrayList allCapabilities,
           ResourceSpecifierFactory rsFactory) {
     // collect all the inputs and all the outputs in 2 Hashtables
     Hashtable mergedInputs = new Hashtable();
     Hashtable mergedOutputs = new Hashtable();
     Iterator allList = allCapabilities.iterator();
     while (allList.hasNext()) {
       Capability entry = (Capability) allList.next();
       // get inputs/outputs for this entry
       TypeOrFeature[] entryInps = entry.getInputs();
       TypeOrFeature[] entryOuts = entry.getOutputs();
       // add/merge inputs in Hashtable
       for (int i = 0; i < entryInps.length; i++) {
         TypeOrFeature nextTof = entryInps[i];
         String name = nextTof.getName();
         TypeOrFeature prevTof = (TypeOrFeature) mergedInputs.get(name);
         if (prevTof != null) {
           // choose next or prev, if it's 'type'
           if (prevTof.isType()) {
             // leave more general one
             if (!prevTof.isAllAnnotatorFeatures() && nextTof.isAllAnnotatorFeatures())
               mergedInputs.put(name, nextTof);
           }
         } else
           // add next ToF
           mergedInputs.put(name, nextTof);
       }
       // add/merge outputs in Hashtable
       for (int i = 0; i < entryOuts.length; i++) {
         TypeOrFeature nextTof = entryOuts[i];
         String name = nextTof.getName();
         TypeOrFeature prevTof = (TypeOrFeature) mergedOutputs.get(name);
         if (prevTof != null) {
           // choose next or prev, if it's 'type'
           if (prevTof.isType()) {
             // leave more general one
             if (!prevTof.isAllAnnotatorFeatures() && nextTof.isAllAnnotatorFeatures())
               mergedOutputs.put(name, nextTof);
           }
         } else
           // add next ToF
           mergedOutputs.put(name, nextTof);
       }
     }
     // create merged Capability object and add merged inputs/outputs
     Capability mergedCapability = rsFactory.createCapability();
     // add merged inputs
     Enumeration inpsList = mergedInputs.keys();
     while (inpsList.hasMoreElements()) {
       String name = (String) inpsList.nextElement();
       TypeOrFeature tof = (TypeOrFeature) mergedInputs.get(name);
       if (tof.isType())
         mergedCapability.addInputType(name, tof.isAllAnnotatorFeatures());
       else
         mergedCapability.addInputFeature(name);
     }
     // add merged outputs
     Enumeration outsList = mergedOutputs.keys();
     while (outsList.hasMoreElements()) {
       String name = (String) outsList.nextElement();
       TypeOrFeature tof = (TypeOrFeature) mergedOutputs.get(name);
       if (tof.isType())
         mergedCapability.addOutputType(name, tof.isAllAnnotatorFeatures());
       else
         mergedCapability.addOutputFeature(name);
     }
     // put merged Capability in the array
     Capability[] mergedArray = new Capability[1];
     mergedArray[0] = mergedCapability;
     return mergedArray;
   }

   /**
    * Creates <code>ResourceSpecifier</code> object for a delegate component descriptor, specified
    * by a given <code>InstallationDescriptor</code> object. Returns the delegate component
    * <code>ResourceSpecifier</code> object.
    *
    * @param aggRootDir
    *          The given aggregate root directory.
    * @param dlgInstDesc
    *          The given delegate <code>InstallationDescriptor</code> object.
    * @return The given delegate component <code>ResourceSpecifier</code> object.
    * @throws IOException
    *           If an I/O exception occurred while creating XML input source.
    * @throws InvalidXMLException
    *           If <code>ResourceSpecifier</code> object cannot be created from the specified
    *           descriptor.
    */
   private static ResourceSpecifier retrieveDelegateSpecifier(File aggRootDir,
           InstallationDescriptor dlgInstDesc) throws IOException, InvalidXMLException {
     // get delegate desciptor path
     String aggRootDirPath = aggRootDir.getAbsolutePath().replace('\\', '/');
     String dlgDescPath = dlgInstDesc.getMainComponentDesc().replaceAll(
             PMControllerHelper.MAIN_ROOT_REGEX, StringUtil.toRegExpReplacement(aggRootDirPath));
     // parse component descriptor
     XMLInputSource xmlSource = null;
     ResourceSpecifier dlgSpecifier = null;
     try {
       xmlSource = new XMLInputSource(dlgDescPath);
       XMLParser xmlParser = UIMAFramework.getXMLParser();
       dlgSpecifier = xmlParser.parseResourceSpecifier(xmlSource);
     } catch (InvalidXMLException xmlExc) {
       String msgKey = xmlExc.getMessageKey();
       // if msg key is INVALID_CLASS, this is TS or RR desc
       if (InvalidXMLException.INVALID_CLASS.equals(msgKey))
         throw new IllegalArgumentException(xmlExc.toString());
       else
         // otherwise, XML descriptor is not valid
         throw xmlExc;
     } catch (UIMA_IllegalStateException urtExc) {
       String msgKey = urtExc.getMessageKey();
       // if msg key is COULD_NOT_INSTANTIATE_XMLIZABLE, this is CPE desc
       if (UIMA_IllegalStateException.COULD_NOT_INSTANTIATE_XMLIZABLE.equals(msgKey))
         throw new IllegalArgumentException(urtExc.toString());
       else
         // otherwise, something is wrong
         throw urtExc;
     } finally {
       if (xmlSource != null) {
         try {
           xmlSource.getInputStream().close();
         } catch (Exception e) {
         }
       }
     }
     return dlgSpecifier;
   }

   /**
    * Saves a given UIMA aggregate component desciption in a specified XML descriptor file.
    *
    * @param aggDescription
    *          The given UIMA aggregate component desciption.
    * @param aggDescFile
    *          The given XML descriptor file.
    * @throws IOException
    *           If an I/O exception occurrs.
    */
   static void saveAggregateDescription(AnalysisEngineDescription aggDescription, File aggDescFile)
           throws IOException {
     FileWriter fWriter = null;
     try {
       fWriter = new FileWriter(aggDescFile);
       aggDescription.toXML(fWriter);
     } catch (SAXException exc) {
       throw new IOException(exc.toString());
     } finally {
       if (fWriter != null) {
         try {
           fWriter.close();
         } catch (Exception e) {
         }
       }
     }
   }

   /**
    * Converts a given <code>XMLizable</code> object to String. This method is useful for
    * debugging.
    *
    * @param content
    *          The given <code>XMLizable</code> object
    * @return A String that represents the given <code>XMLizable</code> object.
    */
   static String toXmlString(XMLizable content) {
     StringWriter sWriter = new StringWriter();
     PrintWriter oWriter = null;
     try {
       oWriter = new PrintWriter(sWriter);
       content.toXML(oWriter);
       oWriter.flush();
     } catch (Exception exc) {
     } finally {
       if (oWriter != null) {
         try {
           oWriter.close();
         } catch (Exception e) {
         }
       }
     }
     return sWriter.toString();
   }
 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License 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.
	*/

	package org.apache.uima.tools.pear.merger;

	import java.io.File;
	import java.io.FileWriter;
	import java.io.IOException;
	import java.io.PrintWriter;
	import java.io.StringWriter;
	import java.util.ArrayList;
	import java.util.Enumeration;
	import java.util.Hashtable;
	import java.util.Iterator;
	import java.util.Map;

	import org.apache.uima.ResourceSpecifierFactory;
	import org.apache.uima.UIMAFramework;
	import org.apache.uima.UIMA_IllegalStateException;
	import org.apache.uima.analysis_engine.AnalysisEngineDescription;
	import org.apache.uima.analysis_engine.TypeOrFeature;
	import org.apache.uima.analysis_engine.metadata.AnalysisEngineMetaData;
	import org.apache.uima.analysis_engine.metadata.FixedFlow;
	import org.apache.uima.collection.CasConsumerDescription;
	import org.apache.uima.pear.tools.InstallationDescriptor;
	import org.apache.uima.pear.util.StringUtil;
	import org.apache.uima.resource.ResourceSpecifier;
	import org.apache.uima.resource.metadata.Capability;
	import org.apache.uima.resource.metadata.Import;
	import org.apache.uima.resource.metadata.OperationalProperties;
	import org.apache.uima.resource.metadata.ProcessingResourceMetaData;
	import org.apache.uima.util.InvalidXMLException;
	import org.apache.uima.util.XMLInputSource;
	import org.apache.uima.util.XMLParser;
	import org.apache.uima.util.XMLizable;
	import org.xml.sax.SAXException;

	/**
	* The <code>PMUimaAgent</code> class implements UIMA-based utility methods utilized by the
	* <code>{@link PMController}</code> class. The class allows generating analysis engine descriptor
	* for output aggregate AE based on the specified input descriptors.
	*/

	public class PMUimaAgent {
	/**
	* Creates UIMA aggregate analysis engine description object, based on given aggregate component name
	* (ID), aggregate root directory and array of delegate installation descriptors. Returns the UIMA
	* aggregate analysis engine description object.
	*
	* @param aggCompName
	* The given aggregate component name (ID).
	* @param aggRootDir
	* The given aggregate root directory.
	* @param dlgInstDescs
	* The given array of delegate installation descriptors.
	* @return The UIMA aggregate analysis engine description object.
	*/
	static AnalysisEngineDescription createAggregateDescription(String aggCompName, File aggRootDir,
	InstallationDescriptor[] dlgInstDescs) {
	AnalysisEngineDescription aggDescription = null;
	int lastInputNo = 0;
	try {
	// get UIMA resource specifier factory
	ResourceSpecifierFactory rsFactory = UIMAFramework.getResourceSpecifierFactory();
	// create aggregate AE description
	aggDescription = rsFactory.createAnalysisEngineDescription();
	aggDescription.setPrimitive(false);
	// get Map of delegate specifiers with imports
	Map delegatesMap = aggDescription.getDelegateAnalysisEngineSpecifiersWithImports();
	// add delegate imports to the Map
	for (int i = 0; i < dlgInstDescs.length; i++) {
	// get delegate component attributes
	InstallationDescriptor dlgInsD = dlgInstDescs[i];
	String dlgName = dlgInsD.getMainComponentId();
	String dlgDescPath = dlgInsD.getMainComponentDesc();
	// create Import for delegate component
	Import dlgImport = rsFactory.createImport();
	// set relative delegate descriptor location
	String dlgDescRelPath = dlgDescPath.replaceAll(PMControllerHelper.MAIN_ROOT_REGEX,
	StringUtil.toRegExpReplacement(".."));
	dlgImport.setLocation(dlgDescRelPath);
	// add delegate Import to the Map
	delegatesMap.put(dlgName, dlgImport);
	}
	// get AE metadata
	AnalysisEngineMetaData aggMetadata = aggDescription.getAnalysisEngineMetaData();
	// set AE name and textual description
	aggMetadata.setName(aggCompName);
	aggMetadata.setDescription("Merged aggregate component" + "(" + PMController.PEAR_MERGER
	+ ")");
	// set fixed flow constraints
	FixedFlow aggFixedFlow = rsFactory.createFixedFlow();
	String[] aggFlowSpecs = new String[dlgInstDescs.length];
	for (int i = 0; i < dlgInstDescs.length; i++)
	aggFlowSpecs[i] = dlgInstDescs[i].getMainComponentId();
	aggFixedFlow.setFixedFlow(aggFlowSpecs);
	aggMetadata.setFlowConstraints(aggFixedFlow);
	// collect capabilities & check operational props of delegates
	ArrayList allCapabilities = new ArrayList();
	boolean isMultipleDeploymentAllowed = true;
	boolean modifiesCas = false;
	for (int i = 0; i < dlgInstDescs.length; i++) {
	lastInputNo = i + 1;
	ResourceSpecifier dlgSpecifier = retrieveDelegateSpecifier(aggRootDir, dlgInstDescs[i]);
	if (dlgSpecifier instanceof AnalysisEngineDescription) {
	// get AE metadata
	AnalysisEngineMetaData dlgAeMetadata = ((AnalysisEngineDescription) dlgSpecifier)
	.getAnalysisEngineMetaData();
	// collect AE capabilities
	Capability[] dlgCapabilities = dlgAeMetadata.getCapabilities();
	if (dlgCapabilities != null)
	for (int n = 0; n < dlgCapabilities.length; n++)
	allCapabilities.add(dlgCapabilities[n]);
	// check operational properties
	OperationalProperties dlgOperProps = dlgAeMetadata.getOperationalProperties();
	if (dlgOperProps != null) {
	if (!dlgOperProps.isMultipleDeploymentAllowed())
	isMultipleDeploymentAllowed = false;
	if (dlgOperProps.getModifiesCas())
	modifiesCas = true;
	} else
	// by default, AE modifies CAS
	modifiesCas = true;
	} else if (dlgSpecifier instanceof CasConsumerDescription) {
	// get CC metadata
	ProcessingResourceMetaData dlgCcMetadata = ((CasConsumerDescription) dlgSpecifier)
	.getCasConsumerMetaData();
	// collect CC capabilities
	Capability[] dlgCapabilities = dlgCcMetadata.getCapabilities();
	if (dlgCapabilities != null)
	for (int n = 0; n < dlgCapabilities.length; n++)
	allCapabilities.add(dlgCapabilities[n]);
	// check operational properties
	OperationalProperties dlgOperProps = dlgCcMetadata.getOperationalProperties();
	if (dlgOperProps != null) {
	if (!dlgOperProps.isMultipleDeploymentAllowed())
	isMultipleDeploymentAllowed = false;
	}
	} else
	// other categories (CR, CI) are not allowed
	throw new IllegalArgumentException("unsupported input component");
	}
	// merge capabilities, excluding duplicates
	Capability[] mergedCapabilities = mergeCapabilities(allCapabilities, rsFactory);
	// set aggregate capabilities
	aggMetadata.setCapabilities(mergedCapabilities);
	// set aggregate operational properties
	OperationalProperties aggOperProps = aggMetadata.getOperationalProperties();
	if (aggOperProps != null) {
	aggOperProps.setMultipleDeploymentAllowed(isMultipleDeploymentAllowed);
	aggOperProps.setModifiesCas(modifiesCas);
	}
	} catch (IllegalArgumentException exc) {
	PMController.logErrorMessage("Invalid input component # " + lastInputNo);
	PMController.logErrorMessage("IllegalArgumentException: " + exc.getMessage());
	aggDescription = null;
	} catch (Throwable err) {
	if (lastInputNo > 0)
	PMController.logErrorMessage("Error in input component # " + lastInputNo);
	PMController.logErrorMessage(err.toString());
	aggDescription = null;
	} finally {
	}
	return aggDescription;
	}

	/**
	* Merges source <code>Capability<code> objects specified in a given
	* <code>ArrayList</code>, creating one <code>Capability<code> object
	* that contains all non-duplicated inputs and outputs of the source
	* <code>Capability<code> objects. Returns an array of
	* <code>Capability<code> objects, containing the merged object.
	*
	* @param allCapabilities The given <code>ArrayList</code> of the source
	* <code>Capability<code> objects.
	* @param rsFactory The <code>ResourceSpecifierFactory</code> object
	* used to create new <code>Capability<code> object.
	* @return Array of <code>Capability<code> objects, containing the merged
	* object.
	*/
	private static Capability[] mergeCapabilities(ArrayList allCapabilities,
	ResourceSpecifierFactory rsFactory) {
	// collect all the inputs and all the outputs in 2 Hashtables
	Hashtable mergedInputs = new Hashtable();
	Hashtable mergedOutputs = new Hashtable();
	Iterator allList = allCapabilities.iterator();
	while (allList.hasNext()) {
	Capability entry = (Capability) allList.next();
	// get inputs/outputs for this entry
	TypeOrFeature[] entryInps = entry.getInputs();
	TypeOrFeature[] entryOuts = entry.getOutputs();
	// add/merge inputs in Hashtable
	for (int i = 0; i < entryInps.length; i++) {
	TypeOrFeature nextTof = entryInps[i];
	String name = nextTof.getName();
	TypeOrFeature prevTof = (TypeOrFeature) mergedInputs.get(name);
	if (prevTof != null) {
	// choose next or prev, if it's 'type'
	if (prevTof.isType()) {
	// leave more general one
	if (!prevTof.isAllAnnotatorFeatures() && nextTof.isAllAnnotatorFeatures())
	mergedInputs.put(name, nextTof);
	}
	} else
	// add next ToF
	mergedInputs.put(name, nextTof);
	}
	// add/merge outputs in Hashtable
	for (int i = 0; i < entryOuts.length; i++) {
	TypeOrFeature nextTof = entryOuts[i];
	String name = nextTof.getName();
	TypeOrFeature prevTof = (TypeOrFeature) mergedOutputs.get(name);
	if (prevTof != null) {
	// choose next or prev, if it's 'type'
	if (prevTof.isType()) {
	// leave more general one
	if (!prevTof.isAllAnnotatorFeatures() && nextTof.isAllAnnotatorFeatures())
	mergedOutputs.put(name, nextTof);
	}
	} else
	// add next ToF
	mergedOutputs.put(name, nextTof);
	}
	}
	// create merged Capability object and add merged inputs/outputs
	Capability mergedCapability = rsFactory.createCapability();
	// add merged inputs
	Enumeration inpsList = mergedInputs.keys();
	while (inpsList.hasMoreElements()) {
	String name = (String) inpsList.nextElement();
	TypeOrFeature tof = (TypeOrFeature) mergedInputs.get(name);
	if (tof.isType())
	mergedCapability.addInputType(name, tof.isAllAnnotatorFeatures());
	else
	mergedCapability.addInputFeature(name);
	}
	// add merged outputs
	Enumeration outsList = mergedOutputs.keys();
	while (outsList.hasMoreElements()) {
	String name = (String) outsList.nextElement();
	TypeOrFeature tof = (TypeOrFeature) mergedOutputs.get(name);
	if (tof.isType())
	mergedCapability.addOutputType(name, tof.isAllAnnotatorFeatures());
	else
	mergedCapability.addOutputFeature(name);
	}
	// put merged Capability in the array
	Capability[] mergedArray = new Capability[1];
	mergedArray[0] = mergedCapability;
	return mergedArray;
	}

	/**
	* Creates <code>ResourceSpecifier</code> object for a delegate component descriptor, specified
	* by a given <code>InstallationDescriptor</code> object. Returns the delegate component
	* <code>ResourceSpecifier</code> object.
	*
	* @param aggRootDir
	* The given aggregate root directory.
	* @param dlgInstDesc
	* The given delegate <code>InstallationDescriptor</code> object.
	* @return The given delegate component <code>ResourceSpecifier</code> object.
	* @throws IOException
	* If an I/O exception occurred while creating XML input source.
	* @throws InvalidXMLException
	* If <code>ResourceSpecifier</code> object cannot be created from the specified
	* descriptor.
	*/
	private static ResourceSpecifier retrieveDelegateSpecifier(File aggRootDir,
	InstallationDescriptor dlgInstDesc) throws IOException, InvalidXMLException {
	// get delegate desciptor path
	String aggRootDirPath = aggRootDir.getAbsolutePath().replace('\\', '/');
	String dlgDescPath = dlgInstDesc.getMainComponentDesc().replaceAll(
	PMControllerHelper.MAIN_ROOT_REGEX, StringUtil.toRegExpReplacement(aggRootDirPath));
	// parse component descriptor
	XMLInputSource xmlSource = null;
	ResourceSpecifier dlgSpecifier = null;
	try {
	xmlSource = new XMLInputSource(dlgDescPath);
	XMLParser xmlParser = UIMAFramework.getXMLParser();
	dlgSpecifier = xmlParser.parseResourceSpecifier(xmlSource);
	} catch (InvalidXMLException xmlExc) {
	String msgKey = xmlExc.getMessageKey();
	// if msg key is INVALID_CLASS, this is TS or RR desc
	if (InvalidXMLException.INVALID_CLASS.equals(msgKey))
	throw new IllegalArgumentException(xmlExc.toString());
	else
	// otherwise, XML descriptor is not valid
	throw xmlExc;
	} catch (UIMA_IllegalStateException urtExc) {
	String msgKey = urtExc.getMessageKey();
	// if msg key is COULD_NOT_INSTANTIATE_XMLIZABLE, this is CPE desc
	if (UIMA_IllegalStateException.COULD_NOT_INSTANTIATE_XMLIZABLE.equals(msgKey))
	throw new IllegalArgumentException(urtExc.toString());
	else
	// otherwise, something is wrong
	throw urtExc;
	} finally {
	if (xmlSource != null) {
	try {
	xmlSource.getInputStream().close();
	} catch (Exception e) {
	}
	}
	}
	return dlgSpecifier;
	}

	/**
	* Saves a given UIMA aggregate component desciption in a specified XML descriptor file.
	*
	* @param aggDescription
	* The given UIMA aggregate component desciption.
	* @param aggDescFile
	* The given XML descriptor file.
	* @throws IOException
	* If an I/O exception occurrs.
	*/
	static void saveAggregateDescription(AnalysisEngineDescription aggDescription, File aggDescFile)
	throws IOException {
	FileWriter fWriter = null;
	try {
	fWriter = new FileWriter(aggDescFile);
	aggDescription.toXML(fWriter);
	} catch (SAXException exc) {
	throw new IOException(exc.toString());
	} finally {
	if (fWriter != null) {
	try {
	fWriter.close();
	} catch (Exception e) {
	}
	}
	}
	}

	/**
	* Converts a given <code>XMLizable</code> object to String. This method is useful for
	* debugging.
	*
	* @param content
	* The given <code>XMLizable</code> object
	* @return A String that represents the given <code>XMLizable</code> object.
	*/
	static String toXmlString(XMLizable content) {
	StringWriter sWriter = new StringWriter();
	PrintWriter oWriter = null;
	try {
	oWriter = new PrintWriter(sWriter);
	content.toXML(oWriter);
	oWriter.flush();
	} catch (Exception exc) {
	} finally {
	if (oWriter != null) {
	try {
	oWriter.close();
	} catch (Exception e) {
	}
	}
	}
	return sWriter.toString();
	}
	}