/*
    * $HeadURL: $
    * $Date: $
    * $Revision: $
    * $Author: $
    * 
    * Copyright (c) 2006 MindTree Consulting Ltd. 
    * 
    * This file is part of Insight.
   * 
   * Insight is free software: you can redistribute it and/or modify it under the 
   * terms of the GNU General Public License as published by the Free Software 
   * Foundation, either version 3 of the License, or (at your option) any later 
   * version.
   * 
   * Insight is distributed in the hope that it will be useful, but 
   * WITHOUT ANY WARRANTY; without even the implied warranty of 
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General 
   * Public License for more details.
   * 
   * You should have received a copy of the GNU General Public License along with 
   * Insight.  If not, see <http://www.gnu.org/licenses/>.
   */
  package com.mindtree.techworks.insight.reporting;
  
  import java.io.IOException;
  import java.io.StringReader;
  import java.io.StringWriter;
  
  import javax.xml.parsers.DocumentBuilder;
  import javax.xml.parsers.DocumentBuilderFactory;
  import javax.xml.parsers.ParserConfigurationException;
  
  import org.apache.xml.serialize.OutputFormat;
  import org.apache.xml.serialize.XMLSerializer;
  import org.w3c.dom.Document;
  import org.w3c.dom.Element;
  import org.w3c.dom.Node;
  import org.w3c.dom.NodeList;
  import org.xml.sax.InputSource;
  import org.xml.sax.SAXException;
  
  
  /**
   * Utility class which has methods for handling common tasks in XML serializing
   * and deserializing <code>Verifier</code>s and <code>Job</code>s.
   *  
   * @author <a href="mailto:bindul_bhowmik@mindtree.com">Bindul Bhowmik</a>
   * @version $Revision: 27 $ $Date: 2007-12-16 04:58:03 -0700 (Sun, 16 Dec 2007) $
   * @since Insight 1.5
   */
  public abstract class SerializationXmlUtils {
  	
  	// -------------------------------------------------------------------------
  	// Constants
  	// -------------------------------------------------------------------------
  	
  	/**
  	 * Characters to escape in XML strings and their replacements.
  	 */
  	private static final String[][] XML_CHARS_TO_ESCAPE = { 
  		{"&", "&amp;"},
  		{"<", "&lt;"},
  		{">", "&gt;"},
  		{"'", "&apos;"},
  		{"\"", "&quot;"}};
  	
  	// -------------------------------------------------------------------------
  	// Public utility methods
  	// -------------------------------------------------------------------------
  
  	/**
  	 * Creates an XML Document from the XML String.
  	 * 
  	 * @param xmlString
  	 *            The Serialized XML.
  	 * @return A <code>Document</code> for the XML passed in.
  	 * @throws InitializationException
  	 *             If there is an exception while parsing the XML.
  	 */
  	public static Document createDocument (String xmlString)
  			throws InitializationException {
  	
  		StringReader reader = new StringReader (xmlString.trim ());
  		InputSource inputSource = new InputSource (reader);
  	
  		DocumentBuilderFactory domFactory = DocumentBuilderFactory
  				.newInstance ();
  		Document document = null;
  	
  		try {
  			DocumentBuilder docBuilder = domFactory.newDocumentBuilder ();
  			document = docBuilder.parse (inputSource);
  		} catch (ParserConfigurationException e) {
  			throw new InitializationException (
  					"Could not parse serialized verifier.", e);
  		} catch (SAXException e) {
  			throw new InitializationException (
  					"Could not parse serialized verifier.", e);
 		} catch (IOException e) {
 			throw new InitializationException (
 					"Could not parse serialized verifier.", e);
 		}
 	
 		return document;
 	}
 
 	/**
 	 * Returns the text value in an XML Element.
 	 * <p>
 	 * If an XML element is passed in in the format
 	 * <code>&lt;element&gt;value&lt;/element&gt;</code>, then the
 	 * <code>value</code> part of it is returned.
 	 * </p>
 	 * <p>
 	 * If the element does not have a text value in it, then <code>null</code>
 	 * is returned.
 	 * </p>
 	 * 
 	 * @param element
 	 *            The element from which the value is to be extracted.
 	 * @return The text value in the element, if present, or <code>null</code>.
 	 */
 	public static String getTextValue (Element element) {
 	
 		String textValue = null;
 	
 		NodeList textNodes = element.getChildNodes ();
 		for (int i = 0; i < textNodes.getLength (); i++ ) {
 			Node textNode = textNodes.item (i);
 			if (textNode.getNodeType () == Node.TEXT_NODE) {
 				textValue = textNode.getNodeValue ();
 				break;
 			}
 		}
 	
 		return textValue;
 	}
 	
 	/**
 	 * Escapes all the special characters to avoid in the value of the string
 	 * representation of the filter criterion.
 	 * 
 	 * @param unescapedString The unescaped string.
 	 * @return String with the special characters escaped.
 	 */
 	public static String escapeSpecialChars (String unescapedString) {
 
 		StringBuffer escapedString = new StringBuffer(unescapedString);
 		
 		// Escape XML special characters
 		for (int i = 0; i < XML_CHARS_TO_ESCAPE.length; i++) {
 			int charIndex = escapedString.indexOf(XML_CHARS_TO_ESCAPE[i][0]);
 			if (charIndex >= 0) {
 				while (charIndex != -1) {
 					escapedString.replace (charIndex, charIndex + 1,
 											XML_CHARS_TO_ESCAPE[i][1]);
 					charIndex = escapedString
 							.indexOf (XML_CHARS_TO_ESCAPE[i][0], charIndex
 									+ XML_CHARS_TO_ESCAPE[i][1].length ());
 				}
 			}
 		}
 		
 		return escapedString.toString();
 	}
 
 	/**
 	 * Serializes the XML element passed in to string format.
 	 * 
 	 * @param element
 	 *            The element to serialize
 	 * @return The serialized XML as a string.
 	 * @throws InitializationException
 	 *             If the underlying implementation cannot serialize the
 	 *             element.
 	 */
 	public static String serializeXmlElement (Element element)
 			throws InitializationException {
 
 		// Format to serialize the XML
 		OutputFormat format = new OutputFormat(element.getOwnerDocument());
 		format.setOmitXMLDeclaration(true);
 
 		// Serializer that will do the job
 		StringWriter writer = new StringWriter();
 		XMLSerializer serializer = new XMLSerializer(writer, format);
 
 		try {
 			serializer.asDOMSerializer();
 			serializer.serialize(element);
 		} catch (IOException ie) {
 			// Should actually never hit this, but still...
 			throw new InitializationException ("Could not serialize element.",
 					ie);
 		}
 		
 		return writer.toString();
 	}
 	
 	/**
 	 * Extracts the class name of the <code>Verfier</code> or the <job> from
 	 * the XML serialized format of it. It uses the XPath
 	 * <code>//(verifier | job)/class</code> to look for the Class name.
 	 * 
 	 * @param serializedVerifier
 	 *            XML Document representing the serialized <code>Verifier</code>.
 	 * @return The class name of the <code>Verifier</code> or <code>Job</code>
 	 *         if present.
 	 * @throws InitializationException
 	 *             If the class name is not present or cannot be read.
 	 */
 	public static String getSerializedObjectClassName (
 			Document serializedVerifier)
 			throws InitializationException {
 
 		// Get the 'class' element.
 		// <verifier> or <job>
 		Element docElement = serializedVerifier.getDocumentElement ();
 		NodeList classElements = docElement.getElementsByTagName ("class");
 
 		// If class elements are not present, then the format is wrong.
 		if (classElements.getLength () == 0) {
 			throw new InitializationException (
 					"Ill formatted verifier / job string: Verifier or Job " +
 					"class name not found.");
 		}
 
 		// Get only the first class, we are not interested in the rest.
 		Element classElement = (Element) classElements.item (0);
 		String className = SerializationXmlUtils.getTextValue (classElement);
 
 		if (null == className || className.trim ().length () == 0) {
 			// Without a class name we cannot regenerate the verifier or job.
 			throw new InitializationException (
 					"Ill formatted verifier / job string: Verifier or Job " +
 					"class name not found.");
 		}
 
 		return className;
 	}
 
 }