Source code: com/aendvari/cerberus/component/assembly/ComponentAssembler.java

   /*
    * ComponentAssembler.java
    *
    * Copyright (c) 2001, 2002 Aendvari, Ltd. All Rights Reserved.
    *
    * See the file LICENSE for terms of use.
    *
    */
   
  package com.aendvari.cerberus.component.assembly;
  
  import java.util.ArrayList;
  import java.util.Collection;
  import java.util.HashSet;
  import java.util.Iterator;
  
  import com.aendvari.cerberus.component.descriptor.*;
  import com.aendvari.cerberus.component.directory.*;
  
  /**
   * <p>Builds the components defined in a {@link AssemblyDescriptor}.</p>
   *
   * <p>The {@link AssemblyContext} may be used to provide context specific
   * information during the build process.</p>
   *
   * @author  Trevor Milne
   *
   */
  
  public class ComponentAssembler
  {
    /** The {@link AssemblyContext} supplying context specific information. */
    private AssemblyContext context;
  
    /** The {@link AssemblyDescriptor} to build the components from. */
    private AssemblyDescriptor assembly;
  
    /** The {@link ComponentDirectory} to register components into. */
    private ComponentDirectory directory;
  
  
    /* Constructors. */
  
  
    /**
     * Constructs a <code>ComponentAssembler</code> instance.
     *
     * The components defined in the supplied {@link AssemblyDescriptor} are assembled
     * in context of the supplied {@link AssemblyContext}.
     *
     * @param    setAssemblyContext      The {@link AssemblyContext} to build with.
     * @param    setAssembly          The {@link AssemblyDescriptor} to build from.
     * @param    setDirectory        The {@link ComponentDirectory} to register components.
     *
     */
  
    public ComponentAssembler(
      AssemblyContext setAssemblyContext, AssemblyDescriptor setAssembly, ComponentDirectory setDirectory)
    {
      context = setAssemblyContext;
      assembly = setAssembly;
      directory = setDirectory;
    }
  
  
    /* Namespaces. */
  
  
    /**
     * Adds the supplied namespace to a property name if one does not exist.
     *
     * @param    namespace          The namespace that uniquely identifies the property.
     * @param    name            The name of the property.
     *
     * @return                  A uniquely identifiable property name.
     *
     */
  
    private String addNamespace(String namespace, String name)
    {
      // check for namespace
      if (name.indexOf('.') < 0)
      {
        // relative attribute name, include namespace
        name = namespace + "." + name;
      }
  
      return name;
    }
  
    /**
     * Allows various resolution methods to act on both attributes and messages.
     *
     */
  
    private interface PropertyResolver
    {
      /**
       * Returns whether the specified property is available within the component definition.
      *
      * @param    definition          The {@link ComponentDefinition} to search.
      * @param    name            The name of the property.
      *
      * @return                  True if the definition contains the named property.
      *
      */
 
     public boolean hasProperty(ComponentDefinition definition, String name);
 
     /**
      * Creates an error message describing an undefined property.
      *
      * @param    property          The name of the property.
      * @param    reference          The context in which the property was referenced.
      *
      * @return                  A string describing the error.
      *
      */
 
     public String getUndefinedPropertyMessage(String property, String reference);
 
     /**
      * Creates an error message describing an ambiguously reference property.
      *
      * @param    property          The name of the property.
      * @param    namespaces          The potential namespaces that could be chosen.
      * @param    reference          The context inwhich the property was referenced.
      *
      * @return                  A string describing the error.
      *
      */
 
     public String getAmbiguousPropertyMessage(String property, Collection namespaces, String reference);
   }
 
   /**
    * An implementation of the {@link PropertyResolver} for component attributes.
    *
    */
 
   private class AttributeResolver implements PropertyResolver
   {
     public boolean hasProperty(ComponentDefinition definition, String name)
     {
       return (definition.getAttribute(name) != null);
     }
 
     public String getUndefinedPropertyMessage(String attribute, String reference)
     {
       // call outer class method
       return createUndefinedPropertyMessage("attribute", attribute, reference);
     }
 
     public String getAmbiguousPropertyMessage(String attribute, Collection namespaces, String reference)
     {
       // call outer class method
       return createAmbiguousPropertyMessage("attribute", attribute, namespaces, reference);
     }
   }
 
   /**
    * An implementation of the {@link PropertyResolver} for component messages.
    *
    */
 
   private class MessageResolver implements PropertyResolver
   {
     public boolean hasProperty(ComponentDefinition definition, String name)
     {
       return (definition.getMessage(name) != null);
     }
 
     public String getUndefinedPropertyMessage(String message, String reference)
     {
       // call outer class method
       return createUndefinedPropertyMessage("message", message, reference);
     }
 
     public String getAmbiguousPropertyMessage(String message, Collection namespaces, String reference)
     {
       // call outer class method
       return createAmbiguousPropertyMessage("message", message, namespaces, reference);
     }
   }
 
   /**
    * Resolves the namespace for the specified property. The definition hierarchy
    * is traversed to find the namespace for the property.
    *
    * @param    definition          The {@link ComponentDefinition} containing the property.
    * @param    property          The name of the property to resolve.
    * @param    resolver          The {@link PropertyResolver} to access property data.
    * @param    context            The current operating context for error reporting.
    *
    * @return                  The resolved property name.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private String resolveProperty(
     ComponentDefinition definition, String property, PropertyResolver resolver, String context)
       throws AssemblyException
   {
     // check for namespace
     if (property.indexOf('.') >= 0)
     {
       // check that reference is valid
       validateProperty(definition, property, resolver, context);
 
       // if namespace available, then no resolution is needed
       return property;
     }
 
     // travel up hierarchy and search for match
     ArrayList searchDefinitions = new ArrayList();
     HashSet searchResults = new HashSet();
 
     // start at local namespace
     searchDefinitions.add(definition);
 
     // continue until all parents have been visited
     while (searchDefinitions.size() > 0)
     {
       // create copy of search list to allow safe iteration
       ArrayList iterationCollection = new ArrayList(searchDefinitions);
       Iterator searchIterator = iterationCollection.iterator();
 
       while (searchIterator.hasNext())
       {
         ComponentDefinition searchDefinition = (ComponentDefinition)searchIterator.next();
 
         // does property exist in this namespace
 
         // make namespace same as current definition
         String potential = addNamespace(searchDefinition.getName(), property);
 
         // search definition
         if (resolver.hasProperty(searchDefinition, potential))
         {
           // property exists, add namespace to result (should be only one)
           searchResults.add(searchDefinition);
         }
         else
         {
           // property not found continue up tree
           Iterator parentIterator = searchDefinition.getParents().iterator();
 
           while (parentIterator.hasNext())
           {
             String parentName = (String)parentIterator.next();
             ComponentDefinition parentDefinition = assembly.getDefinition(parentName);
 
             // add parent to search list
             searchDefinitions.add(parentDefinition);
           }
         }
 
         // remove definition from search list
         searchDefinitions.remove(searchDefinition);
       }
     }
 
     // error if no match was found
     if (searchResults.size() == 0)
     {
       // construct exception message
       String message = resolver.getUndefinedPropertyMessage(property, context);
 
       // throw exception
       throw new AssemblyException(message.toString());
     }
     else
     // error if more than one match was found
     if (searchResults.size() > 1)
     {
       // construct exception message
       String message = resolver.getAmbiguousPropertyMessage(property, searchResults, context);
 
       // throw exception
       throw new AssemblyException(message.toString());
     }
 
     // retrieve property namespace
     ComponentDefinition namespaceDefinition = (ComponentDefinition)searchResults.iterator().next();
 
     String resolved = addNamespace(namespaceDefinition.getName(), property);
 
     return resolved;
   }
 
   /**
    * Determines whether the supplied property name is valid.
    *
    * @param    definition          The {@link ComponentDefinition} containing the property.
    * @param    property          The name of the property to resolve.
    * @param    resolver          The {@link PropertyResolver} to access property data.
    * @param    context            The current operating context for error reporting.
    *
    * @return                  True if the property is valid.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void validateProperty(
     ComponentDefinition definition, String property, PropertyResolver resolver, String context)
       throws AssemblyException
   {
     // extract namespace
     String namespace = property.substring(0, property.indexOf('.'));
 
     // check for valid namespace (definition)
     ComponentDefinition propertyDefinition = assembly.getDefinition(namespace);
 
     if (propertyDefinition == null)
     {
       // construct exception message
       String message = createUndefinedComponentDefinitionMessage(
         namespace, context + "(" + property + ")");
 
       // throw exception
       throw new AssemblyException(message.toString());
     }
 
     // check for valid property within namespace
     if (!resolver.hasProperty(propertyDefinition, property))
     {
       // construct exception message
       String message = resolver.getUndefinedPropertyMessage(property, context);
 
       // throw exception
       throw new AssemblyException(message.toString());
     }
 
     // does namespace exist in active definition
 
     // travel up hierarchy and search for definition
     ArrayList searchDefinitions = new ArrayList();
     HashSet searchResults = new HashSet();
 
     // start at local namespace
     searchDefinitions.add(definition);
 
     // continue until all parents have been visited
     while (searchDefinitions.size() > 0)
     {
       // create copy of search list to allow safe iteration
       ArrayList iterationCollection = new ArrayList(searchDefinitions);
       Iterator searchIterator = iterationCollection.iterator();
 
       while (searchIterator.hasNext())
       {
         ComponentDefinition searchDefinition = (ComponentDefinition)searchIterator.next();
 
         // does the definition exist in the hierarchy
         if (searchDefinition.getName().equals(propertyDefinition.getName()))
         {
           // the property name is valid
           return;
         }
 
         // definition not found continue up tree
         Iterator parentIterator = searchDefinition.getParents().iterator();
 
         while (parentIterator.hasNext())
         {
           String parentName = (String)parentIterator.next();
           ComponentDefinition parentDefinition = assembly.getDefinition(parentName);
 
           // add parent to search list
           searchDefinitions.add(parentDefinition);
         }
 
         // remove definition from search list
         searchDefinitions.remove(searchDefinition);
       }
     }
 
     // the definition could not be found in the heritage
 
     // construct exception message
     String message = createNonParentDefinitionMessage(
       definition.getName(), namespace, context + "(" + property + ")");
 
     // throw exception
     throw new AssemblyException(message.toString());
   }
 
   /**
    * Resolves the namespaces for the attributes referenced within the supplied value.
    *
    * @param    definition          The {@link ComponentDefinition} containing the property.
    * @param    value            The {@link MultiPartValue} to modify.
    * @param    context            The current operating context for error reporting.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void resolveReferencedAttributes(ComponentDefinition definition, MultiPartValue value, String context)
     throws AssemblyException
   {
     // resolve attributes
     PropertyResolver resolver = new AttributeResolver();
 
     // create copy of original value
     MultiPartValue originalValue = new MultiPartValue(value);
 
     // erase value for replacement
     value.clear();
 
     Iterator valueParts = originalValue.getParts().iterator();
 
     while (valueParts.hasNext())
     {
       MultiPartValue.Part part = (MultiPartValue.Part)valueParts.next();
 
       // literal parts stay the same
       if (part.getType() == MultiPartValue.Part.Type.Literal)
       {
         value.addLiteral(part.getValue());
       }
       // attribute references need to be resolved
       else
       {
         String resolved = resolveProperty(definition, part.getValue(), resolver, context);
         value.addAttribute(resolved);
       }
     }
   }
 
   /**
    * Resolves the namespaces for the message referenced within the supplied topic.
    *
    * @param    definition          The {@link ComponentDefinition} containing the message.
    * @param    topic            The {@link MultiPartValue} topic to modify.
    * @param    context            The current operating context for error reporting.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void resolveReferencedMessage(ComponentDefinition definition, MultiPartValue topic, String context)
     throws AssemblyException
   {
     // resolve messages
     PropertyResolver resolver = new MessageResolver();
 
     // get the message name
     String mappedName = ((MultiPartValue.Part)topic.getParts().iterator().next()).getValue();
 
     // erase value for replacement
     topic.clear();
 
     String resolved = resolveProperty(definition, mappedName, resolver, context);
     topic.addAttribute(resolved);
   }
 
   /**
    * Resolves the namespaces and references within the supplied component definition.
    *
    * @param    definition          The {@link ComponentDefinition} to resolve.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void resolveDefinition(ComponentDefinition definition)
     throws AssemblyException
   {
     String context = "the definition " + definition.getName();
 
     // resolve property names
     // if no namespace is specified for property, assume local (definition) namespace
 
     // resolve attributes
     Iterator attributeIterator = new ArrayList(definition.getAttributes()).iterator();
 
     while (attributeIterator.hasNext())
     {
       ComponentAttribute attribute = (ComponentAttribute)attributeIterator.next();
 
       // specify namespace of attribute
       String oldName = attribute.getName();
       String newName = addNamespace(definition.getName(), attribute.getName());
 
       attribute.setName(newName);
 
       definition.updateAttribute(oldName, attribute);
     }
 
     // resolve messages
     Iterator messageIterator = new ArrayList(definition.getMessages()).iterator();
 
     while (messageIterator.hasNext())
     {
       ComponentMessage message = (ComponentMessage)messageIterator.next();
 
       // specify namespace of message
       String oldName = message.getName();
       String newName = addNamespace(definition.getName(), message.getName());
 
       message.setName(newName);
 
       definition.updateMessage(oldName, message);
     }
 
     // resolve property values
     // if no namespace is specified for a referenced property, then search definition
 
     // resolve attributes
     attributeIterator = definition.getAttributes().iterator();
 
     while (attributeIterator.hasNext())
     {
       ComponentAttribute attribute = (ComponentAttribute)attributeIterator.next();
 
       // manipulate attribute values
       resolveReferencedAttributes(definition, attribute.getValue(), context);
     }
 
     // resolve messages
     messageIterator = definition.getMessages().iterator();
 
     while (messageIterator.hasNext())
     {
       ComponentMessage message = (ComponentMessage)messageIterator.next();
 
       // check for mapped message
       if (message.isMapped())
       {
         // manipulate mapped message
         resolveReferencedMessage(definition, message.getTopic(), context);
       }
       else
       {
         // manipulate attribute values
         resolveReferencedAttributes(definition, message.getTopic(), context);
       }
     }
   }
 
   /**
    * Resolves the namespaces and references within the supplied component definitions.
    *
    * @param    definitions          The {@link ComponentDefinition ComponentDefinitions} to resolve.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void resolveDefinitions(Collection definitions)
     throws AssemblyException
   {
     // resolve definition namespaces, visit in order of hierarchy
 
     ArrayList resolvedParents = new ArrayList();
     ArrayList unresolved = new ArrayList(definitions);
 
     // continue until all definitions have been resolved
     while (unresolved.size() > 0)
     {
       // create copy of unresolved list to allow safe iteration
       ArrayList iterationCollection = new ArrayList(unresolved);
       int unresolvedSize = unresolved.size();
 
       // resolve any definitions that have their parents resolved
       Iterator definitionIterator = iterationCollection.iterator();
 
       while (definitionIterator.hasNext())
       {
         ComponentDefinition definition = (ComponentDefinition)definitionIterator.next();
 
         // can be resolved, if all parents have been resolved
         if (resolvedParents.containsAll(definition.getParents()))
         {
           resolveDefinition(definition);
 
           // remove from unresolved list
           unresolved.remove(definition);
 
           // add as potential parent
           resolvedParents.add(definition.getName());
         }
       }
 
       // if no changes were made, then a cycle or undefined parent has been detected
       if (unresolved.size() == unresolvedSize)
       {
         // construct exception message
         String message = createUndefinedParentsMessage(unresolved);
 
         // throw exception
         throw new AssemblyException(message.toString());
       }
     }
   }
 
   /**
    * Resolves the namespaces and references within the supplied component instance.
    *
    * @param    instance          The {@link ComponentInstance} to resolve.
    * @param    definition          The {@link ComponentDefinition} of the instance.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void resolveInstance(ComponentInstance instance, ComponentDefinition definition)
     throws AssemblyException
   {
     PropertyResolver attributeResolver = new AttributeResolver();
     PropertyResolver messageResolver = new MessageResolver();
 
     String context = "the instance " + instance.getName() + "(" + definition.getName() + ")";
 
     // resolve property names
 
     // resolve attributes
     Iterator attributeIterator = new ArrayList(instance.getAttributes()).iterator();
 
     while (attributeIterator.hasNext())
     {
       ComponentAttribute attribute = (ComponentAttribute)attributeIterator.next();
 
       // determine namespace of attribute
       String oldName = attribute.getName();
       String newName = resolveProperty(definition, oldName, attributeResolver, context);
 
       attribute.setName(newName);
 
       instance.updateAttribute(oldName, attribute);
     }
 
     // resolve messages
     Iterator messageIterator = new ArrayList(instance.getMessages()).iterator();
 
     while (messageIterator.hasNext())
     {
       ComponentMessage message = (ComponentMessage)messageIterator.next();
 
       // determine namespace of message
       String oldName = message.getName();
       String newName = resolveProperty(definition, oldName, messageResolver, context);
 
       message.setName(newName);
 
       instance.updateMessage(oldName, message);
     }
 
     // resolve property values
 
     // resolve attributes
     attributeIterator = instance.getAttributes().iterator();
 
     while (attributeIterator.hasNext())
     {
       ComponentAttribute attribute = (ComponentAttribute)attributeIterator.next();
 
       // manipulate attribute values
       resolveReferencedAttributes(definition, attribute.getValue(), context);
     }
 
     // resolve messages
     messageIterator = instance.getMessages().iterator();
 
     while (messageIterator.hasNext())
     {
       ComponentMessage message = (ComponentMessage)messageIterator.next();
 
       // check for mapped message
       if (message.isMapped())
       {
         // manipulate mapped message
         resolveReferencedMessage(definition, message.getTopic(), context);
       }
       else
       {
         // manipulate attribute values
         resolveReferencedAttributes(definition, message.getTopic(), context);
       }
     }
   }
 
 
   /* Assembly. */
 
 
   /**
    * Creates a property value based on the {@link MultiPartValue} and the
    * attributes defined in the {@link ComponentDescriptor}.
    *
    * @param    descriptor          The {@link ComponentDescriptor} for the component.
    * @param    name            The name of the property.
    * @param    value            A {@link MultiPartValue} describing the value.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private String assemblePropertyValue(ComponentDescriptor descriptor, String name, MultiPartValue value)
     throws AssemblyException
   {
     String context = "the attribute " + name + " of the component " + descriptor.getName();
     StringBuffer complete = new StringBuffer();
 
     Iterator partIterator = value.getParts().iterator();
 
     while (partIterator.hasNext())
     {
       // get value part
       MultiPartValue.Part part = (MultiPartValue.Part)partIterator.next();
 
       // translate into string value
       if (part.getType() == MultiPartValue.Part.Type.Literal)
       {
         // append literal value
         complete.append(part.getValue());
       }
       else
       {
         // get attribute
         ComponentDescriptor.Attribute attributeObject = descriptor.getAttribute(part.getValue());
 
         if (attributeObject == null)
         {
           // construct exception message
           String message = createUndefinedPropertyMessage("attribute", part.getValue(), context);
 
           // throw exception
           throw new AssemblyException(message.toString());
         }
 
         // get attribute value
         String attribute = attributeObject.getValue();
 
         // check for null value
         if (attribute == null)
         {
           // construct exception message
           String message = createUndefinedPropertyValueMessage("attribute", part.getValue(), context);
 
           // throw exception
           throw new AssemblyException(message.toString());
         }
 
         // append to value
         complete.append(attribute);
       }
     }
 
     return complete.toString();
   }
 
   /**
    * Checks that the attributes used in the supplied {@link MultiPartValue}
    * have been defined in the {@link ComponentDescriptor}.
    *
    * @param    descriptor          The {@link ComponentDescriptor} for the component.
    * @param    value            A {@link MultiPartValue} describing the value.
    *
    */
 
   private boolean dependenciesAvailable(ComponentDescriptor descriptor, MultiPartValue value)
   {
     Iterator partIterator = value.getParts().iterator();
 
     while (partIterator.hasNext())
     {
       // get value part
       MultiPartValue.Part part = (MultiPartValue.Part)partIterator.next();
 
       // check if values for internal attributes have been provided
       if (part.getType() == MultiPartValue.Part.Type.Attribute)
       {
         // get attribute value
         ComponentDescriptor.Attribute attribute = descriptor.getAttribute(part.getValue());
 
         // check for null value
         if (attribute == null)
         {
           return false;
         }
       }
     }
 
     return true;
   }
 
   /**
    * Creates and stores attribute values in the {@link ComponentDescriptor}.
    * Any attributes referenced by the {@link MultiPartValue} are taken from the other
    * attributes in the {@link ComponentDescriptor}. Those attributes must have their
    * values specified before being used by another attribute.
    *
    * @param    definition          The {@link ComponentDefinition} for the component.
    * @param    instance          The {@link ComponentInstance} for the component.
    * @param    descriptor          The {@link ComponentDescriptor} for the component.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void assembleComponentAttributes(
     ComponentDefinition definition, ComponentInstance instance, ComponentDescriptor descriptor)
       throws AssemblyException
   {
     Collection unresolved = new ArrayList(definition.getAttributes());
 
     // continue looping through attributes until all have been resolved or cycle has been detected
     while (unresolved.size() > 0)
     {
       // make a pass through the attributes and set any that can be resolved
       Collection iterationCollection = new ArrayList(unresolved);
       Iterator attributeIterator = iterationCollection.iterator();
 
       int unresolvedSize = unresolved.size();
 
       while (attributeIterator.hasNext())
       {
         // get attribute definitions
         ComponentAttribute definitionAttribute = (ComponentAttribute)attributeIterator.next();
         ComponentAttribute instanceAttribute = instance.getAttribute(definitionAttribute.getName());
 
         // check if instance provides value
         if (instanceAttribute != null)
         {
           // use value specified by instance
 
           // check if dependent attributes have been resolved
           boolean valid = dependenciesAvailable(descriptor, instanceAttribute.getValue());
 
           if (valid)
           {
             // the value has been specified
 
             // remove attribute from undefined list
             unresolved.remove(definitionAttribute);
 
             // set value in descriptor
             String value = assemblePropertyValue(
               descriptor, instanceAttribute.getName(), instanceAttribute.getValue());
 
             descriptor.addAttribute(definitionAttribute.getName(), definitionAttribute.getAccess(), value);
           }
         }
         else
         {
           // check if attribute already defined (by parent or composite)
           if (descriptor.getAttribute(definitionAttribute.getName()) != null)
           {
             // the value has been specified (typically by composite)
 
             // remove attribute from undefined list
             unresolved.remove(definitionAttribute);
           }
           else
           {
             // check if default value is available in definition
             MultiPartValue defaultValue = definitionAttribute.getValue();
 
             if (defaultValue.getParts().size() > 0)
             {
               // check if dependent attributes have been resolved
               boolean valid = dependenciesAvailable(descriptor, defaultValue);
 
               if (valid)
               {
                 // the value has been specified
 
                 // remove attribute from undefined list
                 unresolved.remove(definitionAttribute);
 
                 // set value in descriptor
                 String value = assemblePropertyValue(
                   descriptor, definitionAttribute.getName(), definitionAttribute.getValue());
 
                 descriptor.addAttribute(definitionAttribute.getName(), definitionAttribute.getAccess(), value);
               }
             }
           }
         }
       }
 
       // check for attribute cycle
       if (unresolved.size() == unresolvedSize)
       {
         // remove any non-required attributes
         iterationCollection = new ArrayList(unresolved);
         attributeIterator = iterationCollection.iterator();
 
         while (attributeIterator.hasNext())
         {
           ComponentAttribute definitionAttribute = (ComponentAttribute)attributeIterator.next();
 
           // non-required attributes do not cause cycle
           if (!definitionAttribute.getRequired())
           {
             unresolved.remove(definitionAttribute);
           }
         }
 
         // check if still unresolved attributes
         if (unresolved.size() == unresolvedSize)
         {
           // construct exception message
           String message = createUnresolvedAttributesMessage(descriptor, unresolved);
 
           // throw exception
           throw new AssemblyException(message.toString());
         }
       }
     }
   }
 
   /**
    * Determines the message topic referenced by the supplied message.
    *
    * @param    descriptor          The {@link ComponentDescriptor} for the component.
    * @param    definitionMessage      The {@link ComponentMessage} of the message definition.
    * @param    resolveMessage        The {@link ComponentMessage} containing the message to resolve.
    * @param    unresolved          The list of currently unresolved messages.
    *
    */
 
   private void mapMessage(
     ComponentDescriptor descriptor,
     ComponentMessage definitionMessage, ComponentMessage resolveMessage,
     Collection unresolved)
   {
     // get name of message, 'topic' contains literal part of mapped message
     String messageName =
       ((MultiPartValue.Part)resolveMessage.getTopic().getParts().iterator().next()).getValue();
 
     // get predefined message from descriptor
     ComponentDescriptor.Message mappedMessage = descriptor.getMessage(messageName);
 
     // check if message has topic
     if (mappedMessage != null)
     {
       // copy message topic
       descriptor.addMessage(
         definitionMessage.getName(), definitionMessage.getType(), definitionMessage.getAccess(),
         mappedMessage.getTopic(), definitionMessage.getSignature());
 
       // remove message from undefined list
       unresolved.remove(definitionMessage);
     }
   }
 
   /**
    * Creates and stores message topic values in the {@link ComponentDescriptor}.
    * Any attributes referenced by the {@link MultiPartValue} are taken from the
    * attributes in the {@link ComponentDescriptor}. Any messages referenced are
    * taken from those in the {@link ComponentDescriptor}.
    *
    * @param    definition          The {@link ComponentDefinition} for the component.
    * @param    instance          The {@link ComponentInstance} for the component.
    * @param    descriptor          The {@link ComponentDescriptor} for the component.
    *
    * @exception  AssemblyException      Thrown when a problem occurs during assembly.
    *
    */
 
   private void assembleComponentMessages(
     ComponentDefinition definition, ComponentInstance instance, ComponentDescriptor descriptor)
       throws AssemblyException
   {
     Collection unresolved = new ArrayList(definition.getMessages());
 
     // continue looping through messages until all have been resolved or cycle has been detected
     while (unresolved.size() > 0)
     {
       // pass through the message and set any that can be resolved
       Collection iterationCollection = new ArrayList(unresolved);
       Iterator messageIterator = definition.getMessages().iterator();
 
       int unresolvedSize = unresolved.size();
 
       while (messageIterator.hasNext())
       {
         // get message definitions
         ComponentMessage definitionMessage = (ComponentMessage)messageIterator.next();
         ComponentMessage instanceMessage = instance.getMessage(definitionMessage.getName());
 
         // check if instance provides value
         if (instanceMessage != null)
         {
           // use topic specified by instance
 
           // check if mapped message
           if (instanceMessage.isMapped())
           {
             // map to the message specified in the instance message
             mapMessage(descriptor, definitionMessage, instanceMessage, unresolved);
           }
           else
           // use value of instance
          {
            // set value in descriptor
            String value = assemblePropertyValue(
              descriptor, instanceMessage.getName(), instanceMessage.getTopic());

            descriptor.addMessage(
              definitionMessage.getName(), definitionMessage.getType(), definitionMessage.getAccess(),
              value, definitionMessage.getSignature());

            // remove message from undefined list
            unresolved.remove(definitionMessage);
          }
        }
        else
        {
          // check if topic already defined (by parent or composite)
          if (descriptor.getMessage(definitionMessage.getName()) != null)
          {
            // the value has been specified (typically by composite)

            // remove message from undefined list
            unresolved.remove(definitionMessage);
          }
          // use topic specified by definition, if any
          else
          {
            // check if mapped message
            if (definitionMessage.isMapped())
            {
              // map to the message specified in the definition message
              mapMessage(descriptor, definitionMessage, definitionMessage, unresolved);
            }
            else
            {
              // check if default topic is available in definition
              MultiPartValue defaultTopic = definitionMessage.getTopic();

              // if available, override any previously defined topic (ie. composite)
              if (defaultTopic.getParts().size() > 0)
              {
                // set value in descriptor
                String value = assemblePropertyValue(
                  descriptor, definitionMessage.getName(), definitionMessage.getTopic());

                descriptor.addMessage(
                  definitionMessage.getName(), definitionMessage.getType(), definitionMessage.getAccess(),
                  value, definitionMessage.getSignature());

                // remove message from undefined list
                unresolved.remove(definitionMessage);
              }
            }
          }
        }
      }

      // check for message mapping cycle
      if (unresolved.size() == unresolvedSize)
      {
        // remove any non-required messages
        iterationCollection = new ArrayList(unresolved);
        messageIterator = iterationCollection.iterator();

        while (messageIterator.hasNext())
        {
          ComponentMessage definitionMessage = (ComponentMessage)messageIterator.next();

          // non-required messages do not cause cycle
          if (!definitionMessage.getRequired())
          {
            unresolved.remove(definitionMessage);
          }
        }

        // check if still unresolved messages
        if (unresolved.size() == unresolvedSize)
        {
          // construct exception message
          String message = createUnresolvedMessageTopicsMessage(descriptor, unresolved);

          // throw exception
          throw new AssemblyException(message.toString());
        }
      }
    }
  }

  /**
   * Creates the specified component from the {@link ComponentInstance} and {@link ComponentDescriptor}.
   *
   * @param    instance          The {@link ComponentInstance} to assemble.
   * @param    definition          The {@link ComponentDefinition} of the component.
   * @param    descriptor          The {@link ComponentDescriptor} to store information.
   *
   * @exception  AssemblyException      Thrown when a problem occurs during assembly.
   *
   */

  private void createComponent(ComponentInstance instance, ComponentDefinition definition, ComponentDescriptor descriptor)
    throws AssemblyException
  {
    try
    {
      // get component class
      Class componentClass = Class.forName(definition.getBackingClass());

      // create instance
      AssembledComponent componentInstance = (AssembledComponent)componentClass.newInstance();

      // provide descriptor to component
      componentInstance.createComponent(context, descriptor);
    }
    catch (ClassNotFoundException exception)
    {
      throw new AssemblyException(exception);
    }
    catch (InstantiationException exception)
    {
      throw new AssemblyException(exception);
    }
    catch (IllegalAccessException exception)
    {
      throw new AssemblyException(exception);
    }
  }

  /**
   * Stores the information of the base definition into the full definition.
   *
   * @param    baseDefinition        The {@link ComponentDefinition} to retrieve data from.
   * @param    fullDefinition        The {@link ComponentDefinition} to store data into.
   *
   */

  private void assembleDefinition(ComponentDefinition baseDefinition, ComponentDefinition fullDefinition)
  {
    // parents are copied into full definition first, children override parent

    // copy parent values
    Iterator parents = baseDefinition.getParents().iterator();

    while (parents.hasNext())
    {
      // get name of definition
      String name = (String)parents.next();

      // add as parent
      fullDefinition.addParent(name);

      // get component definition from assembly descriptor
      ComponentDefinition definition = assembly.getDefinition(name);

      // add parent's information to full definition
      assembleDefinition(definition, fullDefinition);
    }

    // copy attributes
    Iterator attributeIterator = baseDefinition.getAttributes().iterator();

    while (attributeIterator.hasNext())
    {
      ComponentAttribute attribute = (ComponentAttribute)attributeIterator.next();

      fullDefinition.addAttribute(attribute);
    }

    // copy messages
    Iterator messageIterator = baseDefinition.getMessages().iterator();

    while (messageIterator.hasNext())
    {
      ComponentMessage message = (ComponentMessage)messageIterator.next();

      fullDefinition.addMessage(message);
    }

    // copy components
    Iterator componentIterator = baseDefinition.getComponents().iterator();

    while (componentIterator.hasNext())
    {
      ComponentInstance instance = (ComponentInstance)componentIterator.next();

      fullDefinition.addComponent(instance);
    }
  }

  /**
   * Copies the attributes and messages of the source definition into the destination definition.
   * The source definition becomes an implicit parent of the destination definition.
   *
   * @param    source            The source {@link ComponentDefinition}.
   * @param    destination          The destination {@link ComponentDefinition}.
   *
   * @exception  AssemblyException      Thrown when a problem occurs during assembly.
   *
   */

  private void includeDefinition(ComponentDefinition source, ComponentDefinition destination)
    throws AssemblyException
  {
    // source definition as parent of definition
    if (source.getName() != null)
    {
      destination.addParent(source.getName());
    }

    // add parents
    Iterator parentIterator = source.getParents().iterator();

    while (parentIterator.hasNext())
    {
      String parent = (String)parentIterator.next();
      destination.addParent(parent);
    }

    // add attributes
    Iterator attributeIterator = source.getAttributes().iterator();

    while (attributeIterator.hasNext())
    {
      ComponentAttribute attribute = (ComponentAttribute)attributeIterator.next();
      destination.addAttribute(attribute);
    }

    // add messages
    Iterator messageIterator = source.getMessages().iterator();

    while (messageIterator.hasNext())
    {
      ComponentMessage message = (ComponentMessage)messageIterator.next();
      destination.addMessage(message);
    }
  }

  /**
   * Creates a new descriptor containing only attributes and messages of the
   * specified definition. Elliminates temporary properties built during assembly.
   * Whenever possible, simple references (no namespace) to attributes and messages
   * are created.
   *
   * @param    definition          The instance {@link ComponentDefinition}.
   * @param    descriptor          The {@link ComponentDescriptor} containing final values.
   *
   * @return                  A descriptor containing only those properties in the definition.
   *
   * @exception  AssemblyException      Thrown when a problem occurs during assembly.
   *
   */

  private ComponentDescriptor createDefinitionDescriptor(ComponentDefinition specification, ComponentDescriptor descriptor)
    throws AssemblyException
  {
    // create basic definition (do not include owning composite)
    ComponentDefinition definition = new ComponentDefinition();

    definition.setName(specification.getName());
    assembleDefinition(specification, definition);

    // create empty descriptor
    ComponentDescriptor definitionDescriptor = new ComponentDescriptor();

    // add attributes
    PropertyResolver attributeResolver = new AttributeResolver();
    Iterator attributeIterator = definition.getAttributes().iterator();

    while (attributeIterator.hasNext())
    {
      ComponentAttribute definitionAttribute = (ComponentAttribute)attributeIterator.next();

      ComponentDescriptor.Attribute descriptorAttribute =
        (ComponentDescriptor.Attribute)descriptor.getAttribute(definitionAttribute.getName());

      // if no value provided, then skip attribute
      if (descriptorAttribute == null)
      {
        continue;
      }

      // add attribute
      definitionDescriptor.addAttribute(
        descriptorAttribute.getName(), descriptorAttribute.getAccess(), descriptorAttribute.getValue());

      // consider simple name
      String simple = descriptorAttribute.getName().substring(descriptorAttribute.getName().indexOf('.') + 1);

      try
      {
        // check if simple is immediately available
        String resolved = resolveProperty(definition, simple, attributeResolver, "");

        // if resolved is same, then a simple reference is valid
        if (descriptorAttribute.getName().equals(resolved))
        {
          // add attribute as simple name
          definitionDescriptor.addAttribute(
            simple, descriptorAttribute.getAccess(), descriptorAttribute.getValue());
        }
      }
      catch (AssemblyException exception)
      {
        // several attributes having simple name were found, can not add as simple
      }
    }

    // add messages
    PropertyResolver messageResolver = new MessageResolver();
    Iterator messageIterator = definition.getMessages().iterator();

    while (messageIterator.hasNext())
    {
      ComponentMessage definitionMessage = (ComponentMessage)messageIterator.next();

      ComponentDescriptor.Message descriptorMessage =
        (ComponentDescriptor.Message)descriptor.getMessage(definitionMessage.getName());

      // if no value provided, then skip message
      if (descriptorMessage == null)
      {
        continue;
      }

      // add message
      definitionDescriptor.addMessage(
        descriptorMessage.getName(), descriptorMessage.getType(), descriptorMessage.getAccess(),
        descriptorMessage.getTopic(), descriptorMessage.getSignature());

      // consider simple name
      String simple = descriptorMessage.getName().substring(descriptorMessage.getName().indexOf('.') + 1);

      try
      {
        // check if simple is immediately available
        String resolved = resolveProperty(definition, simple, messageResolver, "");

        // if resolved is same, then a simple reference is valid
        if (descriptorMessage.getName().equals(resolved))
        {
          // add attribute as simple name
          definitionDescriptor.addMessage(
            simple, descriptorMessage.getType(), descriptorMessage.getAccess(),
            descriptorMessage.getTopic(), descriptorMessage.getSignature());
        }
      }
      catch (AssemblyException exception)
      {
        // several messages having simple name were found, can not add as simple
      }
    }

    return definitionDescriptor;
  }

  /**
   * Assembles the specified component from the {@link ComponentInstance}.
   *
   * @param    instanceNamespace      The prefix to uniquely identify this component instance.
   * @param    instance          The {@link ComponentInstance} to assemble.
   * @param    ownerDefinition        The {@link ComponentDefinition} of the owning composite.
   * @param    ownerDescriptor        The {@link ComponentDescriptor} of the owning composite.
   *
   * @exception  AssemblyException      Thrown when a problem occurs during assembly.
   *
   */

  private void assembleComponent(
    String instanceNamespace, ComponentInstance instance,
    ComponentDefinition ownerDefinition, ComponentDescriptor ownerDescriptor)
      throws AssemblyException
  {
    // check for instance name
    if (instance.getName() == null)
    {
      // construct exception message
      String message = createUndefinedInstanceName(instance.getDefinition());

      // throw exception
      throw new AssemblyException(message.toString());
    }

    // get component definition
    ComponentDefinition specification = assembly.getDefinition(instance.getDefinition());

    if (specification == null)
    {
      // construct exception message
      String message = createUndefinedComponentDefinitionMessage(instance.getName(), instance.getDefinition());

      // throw exception
      throw new AssemblyException(message.toString());
    }

    // create full definition
    ComponentDefinition definition = new ComponentDefinition();

    // can't use copy constructor since sub-components would be included
    // and assembleDefinition() would include them a second time

    // copy basic information
    definition.setName(specification.getName());
    definition.setBackingClass(specification.getBackingClass());

    // copy specification parents
    Iterator parentIterator = specification.getParents().iterator();

    while (parentIterator.hasNext())
    {
      String parent = (String)parentIterator.next();
      definition.addParent(parent);
    }

    // include owning composite, heritage of owner has already been built
    // only copy parents, attributes, and messages, ignore components
    includeDefinition(ownerDefinition, definition);

    // include heritage
    assembleDefinition(specification, definition);