/*
    * Copyright 2008-2010 smartics, Kronseder & Reiner GmbH
    *
    * Licensed 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 de.smartics.maven.issues.cache;
  
  import java.io.Closeable;
  import java.lang.reflect.Constructor;
  import java.util.HashMap;
  import java.util.Map;
  
  import javax.xml.namespace.QName;
  import javax.xml.stream.XMLStreamConstants;
  import javax.xml.stream.XMLStreamException;
  import javax.xml.stream.XMLStreamReader;
  
  import org.apache.commons.logging.Log;
  import org.apache.commons.logging.LogFactory;
  import org.eclipse.mylyn.tasks.core.TaskRepository;
  import org.eclipse.mylyn.tasks.core.data.TaskAttribute;
  import org.eclipse.mylyn.tasks.core.data.TaskAttributeMapper;
  import org.eclipse.mylyn.tasks.core.data.TaskAttributeMetaData;
  import org.eclipse.mylyn.tasks.core.data.TaskData;
  
  /**
   * Reads a task from a given stream.
   *
   * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
   * @version $Revision:591 $
   */
  public class XmlTaskReader implements Closeable
  { // NOPMD
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    // --- members --------------------------------------------------------------
  
    /**
     * Reference to the logger for this class.
     */
    private final Log log = LogFactory.getLog(XmlTaskReader.class);
  
    /**
     * The reader to read single tasks from.
     */
    protected final XMLStreamReader xmlReader;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Default constructor.
     *
     * @param xmlReader the reader to read single tasks from.
     * @throws NullPointerException if the <code>xmlWriter</code> is
     *           <code>null</code>.
     */
    public XmlTaskReader(final XMLStreamReader xmlReader)
      throws NullPointerException
    {
      if (xmlReader == null)
      {
        throw new NullPointerException("XML reader must not be 'null'.");
      }
      this.xmlReader = xmlReader;
    }
  
    // ****************************** Inner Classes *****************************
  
    // ********************************* Methods ********************************
  
    // --- init -----------------------------------------------------------------
  
    // --- get&set --------------------------------------------------------------
  
    // --- business -------------------------------------------------------------
  
    /**
     * Reads the task from the given XML stream.
     *
     * @return the task instance constructed from the information read from the
     *         given stream, <code>null</code> if no element is on the stream.
     * @throws XMLStreamException if the information cannot be read from the
     *           stream.
     */
   public TaskData readTask() throws XMLStreamException
   {
     if (xmlReader.hasNext())
     {
       xmlReader.nextTag();
       final QName qNameRoot = xmlReader.getName();
       final String giRoot = qNameRoot.getLocalPart();
       if (!TaskInfoKey.TASK_DATA.equals(giRoot))
       {
         throw new XMLStreamException("Expected '" + TaskInfoKey.TASK_DATA
                                      + "' but encountered '" + giRoot + "'.");
       }
 
       return readTaskData(giRoot);
     }
     return null;
   }
 
   /**
    * Reads the task data from the stream.
    *
    * @param giRoot the root element for logging.
    * @return the read task data instance.
    * @throws XMLStreamException if the task data cannot be read.
    */
   private TaskData readTaskData(final String giRoot) throws XMLStreamException
   {
     final TaskData taskData = createTaskData();
 
     if (xmlReader.hasNext())
     {
       xmlReader.nextTag();
       final QName qName = xmlReader.getName();
       final String gi = qName.getLocalPart();
       if (TaskInfoKey.ATTRIBUTE.equals(gi))
       {
         provideAttribute(taskData.getRoot());
       }
       else
       {
         if (log.isDebugEnabled())
         {
           log.debug(createUnrecognizedElementMessage(giRoot, gi));
         }
       }
     }
     return taskData;
   }
 
   /**
    * Creates a log message for unrecognized elements.
    *
    * @param parentElementGi the element within which the <code>gi</code> was
    *          encountered unexpectedly.
    * @param nestedElementGi the generic identifier of the element within
    *          <code>parentElement</code> that was not expected to be
    *          encountered.
    * @return a message to be logged.
    */
   private static String createUnrecognizedElementMessage(
       final String parentElementGi, final String nestedElementGi)
   {
     return "Unrecognized tag within '" + parentElementGi + "': "
            + nestedElementGi;
   }
 
   /**
    * Creates the task data instance containing basic information required to be
    * passed to the constructor.
    *
    * @return the instantiated task data.
    * @throws XMLStreamException if the instance cannot be created due to reading
    *           problems or invalid information on the stream.
    */
   public TaskData createTaskData() throws XMLStreamException
   {
     final Map<String, String> properties = readElementAttributes();
     final TaskData taskData = createTaskData(properties);
     return taskData;
   }
 
   /**
    * Reads the attributes of the current element.
    *
    * @return the map of attributes read.
    * @throws XMLStreamException if there is an error reading from the stream.
    */
   private Map<String, String> readElementAttributes() throws XMLStreamException
   {
     final int attributeCount = xmlReader.getAttributeCount();
     final Map<String, String> attributes = new HashMap<String, String>();
     for (int i = 0; i < attributeCount; i++)
     {
       final String name = xmlReader.getAttributeLocalName(i);
       final String value = xmlReader.getAttributeValue(i);
       attributes.put(name, value);
     }
     return attributes;
   }
 
   /**
    * Instantiates the task data from the properties given.
    *
    * @param properties the properties containing <code></code>
    * @return the task data instance with basic information set.
    * @throws XMLStreamException if the instance cannot be created for whatever
    *           reason.
    */
   private TaskData createTaskData(final Map<String, String> properties)
     throws XMLStreamException
   {
     try
     {
       final Constructor<TaskData> constructor =
           TaskData.class.getConstructor(TaskAttributeMapper.class,
               String.class, String.class, String.class);
       final String taskId = properties.get(TaskInfoKey.TASK_ID);
       final String repositoryUrl = properties.get(TaskInfoKey.REPOSITORY_URL);
       final String connectorKind = properties.get(TaskInfoKey.CONNECTOR_KIND);
 
       final TaskRepository taskRepository =
           new TaskRepository(connectorKind, repositoryUrl);
       final TaskAttributeMapper mapper =
           new TaskAttributeMapper(taskRepository);
 
       final TaskData taskData =
           constructor.newInstance(mapper, connectorKind, repositoryUrl, taskId);
       final String version = properties.get(TaskInfoKey.VERSION);
       if (version != null)
       {
         taskData.setVersion(version);
       }
       return taskData;
     }
     catch (final Exception e)
     {
       throw new XMLStreamException("Cannot create task data with properties: "
                                    + properties, e);
     }
   }
 
   /**
    * Reads the attribute's information from the stream.
    *
    * @param attribute the attribute whose information is about to be read.
    * @throws XMLStreamException if there is a problem reading the attribut's
    *           information.
    */
   private void provideAttribute(final TaskAttribute attribute)
     throws XMLStreamException
   {
     while (xmlReader.hasNext())
     {
       xmlReader.nextTag();
       final QName qName = xmlReader.getName();
       final String gi = qName.getLocalPart();
       if (TaskInfoKey.ATTRIBUTE.equals(gi))
       {
         return;
       }
       else
       {
         readNextInformation(attribute, gi);
       }
     }
   }
 
   /**
    * Reads the next attribute information.
    *
    * @param attribute the attribute whose information is about to be read.
    * @param gi selector to check which information is next on the stream.
    * @throws XMLStreamException if there is a problem reading the attribut's
    *           information.
    */
   private void readNextInformation(final TaskAttribute attribute,
       final String gi) throws XMLStreamException
   {
     if (TaskInfoKey.ATTRIBUTES.equals(gi))
     {
       provideAttributes(attribute);
     }
     else if (TaskInfoKey.OPTIONS.equals(gi))
     {
       provideOptions(attribute);
     }
     else if (TaskInfoKey.META_DATA.equals(gi))
     {
       provideMetaData(attribute);
     }
     else if (TaskInfoKey.VALUES.equals(gi))
     {
       provideValues(attribute);
     }
     else
     {
       if (log.isDebugEnabled())
       {
         log.debug(createUnrecognizedElementMessage(TaskInfoKey.ATTRIBUTE, gi));
       }
     }
   }
 
   /**
    * Reads the attribute's meta data from the stream.
    *
    * @param attribute the attribute the meta data will be written to.
    * @throws XMLStreamException if there is a problem reading the meta data.
    */
   private void provideMetaData(final TaskAttribute attribute)
     throws XMLStreamException
   {
     final TaskAttributeMetaData metaData = attribute.getMetaData();
     while (xmlReader.hasNext())
     {
       xmlReader.nextTag();
       final QName qName = xmlReader.getName();
       final String gi = qName.getLocalPart();
       if (TaskInfoKey.META_DATA.equals(gi))
       {
         return;
       }
       else if (xmlReader.getEventType() == XMLStreamConstants.END_ELEMENT)
       {
         continue;
       }
       else
       {
         if (TaskInfoKey.ENTRY.equals(gi))
         {
           final String key = readSimpleElement(TaskInfoKey.KEY);
           final String value = readSimpleElement(TaskInfoKey.VALUE);
           metaData.putValue(key, value);
           xmlReader.nextTag();
         }
         else
         {
           if (log.isDebugEnabled())
           {
             log.debug(createUnrecognizedElementMessage(TaskInfoKey.META_DATA,
                 gi));
           }
         }
       }
     }
   }
 
   /**
    * Reads an element that contains only text.
    *
    * @param expectedGi the expected generic identifier (GI) of the element.
    * @return the text content of the element.
    * @throws XMLStreamException if the GI or text content cannot be read.
    */
   private String readSimpleElement(final String expectedGi)
     throws XMLStreamException
   {
     xmlReader.nextTag();
     final QName qName = xmlReader.getName();
     final String gi = qName.getLocalPart();
     if (expectedGi.equals(gi))
     {
       xmlReader.next();
       final String value = readCharacters();
       return value;
     }
     else
     {
       throw new XMLStreamException("Expected '" + expectedGi + "' but found '"
                                    + gi + "'.");
     }
   }
 
   /**
    * Reads the attribute's options from the stream.
    *
    * @param attribute the attribute the options will be written to.
    * @throws XMLStreamException if there is a problem reading the options.
    */
   private void provideOptions(final TaskAttribute attribute)
     throws XMLStreamException
   {
     while (xmlReader.hasNext())
     {
       xmlReader.nextTag();
       final QName qName = xmlReader.getName();
       final String gi = qName.getLocalPart();
       if (TaskInfoKey.OPTIONS.equals(gi))
       {
         return;
       }
       else if (xmlReader.getEventType() == XMLStreamConstants.END_ELEMENT)
       {
         continue;
       }
       else
       {
         if (TaskInfoKey.ENTRY.equals(gi))
         {
           final String key = readSimpleElement(TaskInfoKey.KEY);
           final String value = readSimpleElement(TaskInfoKey.VALUE);
           attribute.putOption(key, value);
           xmlReader.nextTag();
         }
         else
         {
           if (log.isDebugEnabled())
           {
             log.debug(createUnrecognizedElementMessage(TaskInfoKey.OPTIONS, gi));
           }
         }
       }
     }
   }
 
   /**
    * Adds values to the attribute.
    *
    * @param attribute the attribute whose values are about to be read.
    * @throws XMLStreamException if there is a problem reading the attribute's
    *           values.
    */
   private void provideValues(final TaskAttribute attribute)
     throws XMLStreamException
   {
     xmlReader.nextTag();
     while (xmlReader.hasNext())
     {
       final QName qName = xmlReader.getName();
       final String gi = qName.getLocalPart();
       if (TaskInfoKey.VALUES.equals(gi))
       {
         return;
       }
       else if (xmlReader.getEventType() == XMLStreamConstants.END_ELEMENT)
       {
         xmlReader.nextTag();
         continue;
       }
       else if (TaskInfoKey.VALUE.equals(gi))
       {
         xmlReader.next();
         final String value = readCharacters();
         attribute.addValue(value);
       }
     }
   }
 
   /**
    * Reads all character elements until any other element is encountered. The
    * content of all elements is returned as one string.
    *
    * @return the string containing all characters of subsequent
    *         {@link XMLStreamConstants#CHARACTER characters}.
    * @throws XMLStreamException if the characters cannot be read.
    */
   private String readCharacters() throws XMLStreamException
   {
     final StringBuilder buffer = new StringBuilder();
     while (xmlReader.getEventType() == XMLStreamConstants.CHARACTERS)
     {
       buffer.append(xmlReader.getText());
       xmlReader.next();
     }
     return buffer.toString();
   }
 
   /**
    * Provides the sub attributes for the given attribute.
    *
    * @param attribute the parent attribute to the attributes being read.
    * @throws XMLStreamException if there is a problem reading the attributes.
    */
   private void provideAttributes(final TaskAttribute attribute)
     throws XMLStreamException
   {
     while (xmlReader.hasNext())
     {
       xmlReader.nextTag();
       final QName qName = xmlReader.getName();
       final String gi = qName.getLocalPart();
       if (TaskInfoKey.ATTRIBUTES.equals(gi))
       {
         return;
       }
       else
       {
         final String attributeId = getAttribute(TaskInfoKey.ATTRIBUTE_ID);
         final TaskAttribute subAttribute =
             new TaskAttribute(attribute, attributeId); // NOPMD
         provideAttribute(subAttribute);
       }
     }
 
   }
 
   /**
    * A convenience method if just one single attribute of an element is
    * requested.
    *
    * @param name the name of the attribute to return.
    * @return the value of the attribute with the given <code>name</code>.
    * @throws XMLStreamException if there is a problem reading the current
    *           element's attributes.
    */
   private String getAttribute(final String name) throws XMLStreamException
   {
     final Map<String, String> attributes = readElementAttributes();
     return attributes.get(name);
   }
 
   /**
    * {@inheritDoc}
    * <p>
    * The stream is closed quietly, logging any failure at error level.
    * </p>
    *
    * @see java.io.Closeable#close()
    */
   public void close()
   {
     try
     {
       this.xmlReader.close();
     }
     catch (final XMLStreamException e)
     {
       if (log.isErrorEnabled())
       {
         log.error("Cannot close XML stream of task reader.");
       }
     }
   }
 
   // --- object basics --------------------------------------------------------
 
 }