| /* Derby - Class org.apache.derbyBuild.GeneratorBase |
| |
| 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.derbyBuild; |
| |
| import java.io.*; |
| import java.util.*; |
| import javax.xml.parsers.*; |
| import javax.xml.transform.*; |
| import javax.xml.transform.dom.*; |
| import javax.xml.transform.stream.*; |
| import org.w3c.dom.*; |
| |
| import org.apache.tools.ant.BuildException; |
| import org.apache.tools.ant.Project; |
| import org.apache.tools.ant.Task; |
| |
| /** |
| * |
| */ |
| public class GeneratorBase extends Task { |
| ///////////////////////////////////////////////////////////////////////// |
| // |
| // CONSTANTS |
| // |
| ///////////////////////////////////////////////////////////////////////// |
| |
| // header levels |
| protected static final int BANNER_LEVEL = 1; |
| protected static final int MAIN_SECTION_LEVEL = BANNER_LEVEL + 1; |
| protected static final int ISSUE_DETAIL_LEVEL = MAIN_SECTION_LEVEL + 1; |
| // headlines |
| protected static final String DESCRIPTION_HEADLINE = "Description"; |
| protected static final String ISSUE_ID_HEADLINE = "Issue Id"; |
| |
| // formatting tags |
| private static final String ANCHOR = "a"; |
| protected static final String BODY = "body"; |
| private static final String BOLD = "b"; |
| private static final String BORDER = "border"; |
| private static final String COLUMN = "td"; |
| private static final String COLUMN_HEADER = "th"; |
| private static final String HORIZONTAL_LINE = "hr"; |
| protected static final String HTML = "html"; |
| private static final String DIVISION = "div"; |
| private static final String LIST = "ul"; |
| private static final String LIST_ELEMENT = "li"; |
| private static final String NAME = "name"; |
| protected static final String PARAGRAPH = "p"; |
| private static final String ROW = "tr"; |
| protected static final String SPAN = "span"; |
| private static final String TABLE = "table"; |
| |
| // tags in summary xml |
| private static final String SUM_PREVIOUS_RELEASE_ID = "previousReleaseID"; |
| private static final String SUM_RELEASE_ID = "releaseID"; |
| private static final String SUM_EXCLUDE_RELEASE_ID = "excludeReleaseID"; |
| |
| // other html control |
| protected static final int DEFAULT_TABLE_BORDER_WIDTH = 2; |
| |
| protected DocumentBuilder docBldr = |
| DocumentBuilderFactory.newInstance().newDocumentBuilder(); |
| ///////////////////////////////////////////////////////////////////////// |
| // |
| // STATE |
| // |
| ///////////////////////////////////////////////////////////////////////// |
| // set on the command line or by ant |
| // Summary file |
| protected String summaryFileName; |
| protected Document summaryDoc; |
| protected ElementFacade summary; |
| // Bug list file |
| protected String bugListFileName; |
| protected List bugList; |
| |
| // Output file |
| private String outputFileName; |
| protected Document outputDoc = docBldr.newDocument(); |
| protected File outputFile; |
| |
| // computed at run time |
| protected String releaseID; |
| protected String previousReleaseID; |
| protected List<String> excludeReleaseIDList; |
| protected final String branch; |
| protected ArrayList<String> errors = new ArrayList<String>(); |
| |
| // misc |
| protected boolean _invokedByAnt = true; |
| |
| /** |
| * Establishes state, including branch number. |
| * @throws java.lang.Exception |
| */ |
| public GeneratorBase() throws Exception { |
| Properties r = new Properties(); |
| r.load(new FileInputStream("../ant/properties/release.properties")); |
| int maint = Integer.parseInt(r.getProperty("maint")); |
| branch = r.getProperty("eversion"); |
| } |
| |
| ///////////////////////////////////////////////////////////////////////// |
| // |
| // ANT Task BEHAVIOR |
| // |
| ///////////////////////////////////////////////////////////////////////// |
| /** |
| * Ant accessor to set the name of the summary file prepared by the |
| * Release Manager |
| * @param summaryFileName name of xml file to use for the summary |
| * @throws Exception |
| */ |
| public void setSummaryFileName(String summaryFileName) throws Exception { |
| this.summaryFileName = summaryFileName; |
| summaryDoc = docBldr.parse(new File(summaryFileName)); |
| summary = new ElementFacade(summaryDoc); |
| previousReleaseID = summary.getTextByTagName(SUM_PREVIOUS_RELEASE_ID); |
| |
| excludeReleaseIDList = |
| summary.getTextListByTagName(SUM_EXCLUDE_RELEASE_ID); |
| System.out.println("Summary file (input): " + summaryFileName); |
| } |
| |
| /** |
| * Ant mutator to set the name of the JIRA-generated list of bugs |
| * addressed by this release |
| * @param bugListFileName name of an xml file from a Jira filter/query |
| * @throws Exception |
| */ |
| public void setBugListFileName(String bugListFileName) throws Exception { |
| this.bugListFileName = bugListFileName; |
| } |
| |
| /** |
| * Ant mutator to set the name of the generated output file |
| * @param outputFileName name of file to use as pamphlet (output) |
| * @throws Exception |
| */ |
| public void setOutputFileName(String outputFileName) throws Exception { |
| this.outputFileName = outputFileName; |
| outputFile = new File(outputFileName); |
| } |
| |
| /** |
| * Ant mutator to set the id of the release |
| */ |
| public void setReleaseId(String releaseID) throws Exception { |
| this.releaseID = releaseID; |
| } |
| |
| ///////////////////////////////////////////////////////////////////////// |
| // |
| // MINIONS |
| // |
| ///////////////////////////////////////////////////////////////////////// |
| /** |
| * Note that this release is a delta from the previous one. |
| * @param parent |
| * @throws java.lang.Exception |
| */ |
| protected void buildDelta(Element parent) |
| throws Exception { |
| String deltaStatement = |
| "These notes describe the difference between Apache Derby release " + |
| releaseID + " and the preceding release " + |
| previousReleaseID + "."; |
| |
| addParagraph(parent, deltaStatement); |
| } |
| |
| /** |
| * Replace the known parameters with their corresponding text values. |
| * @throws Exception |
| */ |
| protected void replaceVariables() |
| throws Exception { |
| replaceTag(outputDoc, SUM_RELEASE_ID, releaseID); |
| replaceTag(outputDoc, SUM_PREVIOUS_RELEASE_ID, previousReleaseID); |
| } |
| |
| /** |
| * Print the generated output document to the output file. |
| * @throws Exception |
| */ |
| protected void printOutput() throws Exception { |
| Source source = new DOMSource(outputDoc); |
| |
| Result result = new StreamResult(outputFile); |
| Transformer transformer = |
| TransformerFactory.newInstance().newTransformer(); |
| |
| transformer.transform(source, result); |
| } |
| |
| /** |
| * Print accumulated errors. |
| * @throws Exception |
| */ |
| protected void printErrors() throws Exception { |
| if (errors.isEmpty()) { |
| return; |
| } |
| |
| println("The following other errors occurred:"); |
| |
| for (Iterator i = errors.iterator(); i.hasNext();) { |
| println("\n" + i.next()); |
| } |
| } |
| |
| |
| //////////////////////////////////////////////////////// |
| // |
| // HTML MINIONS |
| // |
| //////////////////////////////////////////////////////// |
| /** |
| * Create a section at the end of a parent element and link to it from a |
| * table of contents. |
| * @param parent in document tree |
| * @param sectionLevel in document |
| * @param toc table of content element |
| * @param sectionName for section being created |
| * @param tocEntry key into table of content |
| * @return resulting Element |
| * @throws Exception |
| */ |
| public static Element createSection(Element parent, int sectionLevel, |
| Element toc, String sectionName, String tocEntry) |
| throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Text textNode = doc.createTextNode(tocEntry); |
| |
| return createSection(parent, sectionLevel, toc, sectionName, textNode); |
| } |
| |
| /** |
| * Create a section at the end of a parent element and link to it from a |
| * table of contents. |
| * @param parent in document tree |
| * @param sectionLevel in document |
| * @param toc table of content element |
| * @param sectionName for section being created |
| * @param visibleText text to show |
| * @return resulting Element |
| * @throws Exception |
| */ |
| public static Element createSection(Element parent, int sectionLevel, |
| Element toc, String sectionName, Node visibleText) |
| throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Element link = createLocalLink(doc, sectionName, visibleText); |
| |
| addListItem(toc, link); |
| |
| return createHeader(parent, sectionLevel, sectionName); |
| } |
| |
| /** |
| * Create a header at the end of the parent node. Return the block created |
| * to hold the text following this header. |
| * @param parent |
| * @param headerLevel |
| * @param text |
| * @return created header Element |
| * @throws Exception |
| */ |
| public static Element createHeader(Element parent, int headerLevel, |
| String text) throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Text textNode = doc.createTextNode(text); |
| Element header = doc.createElement(makeHeaderTag(headerLevel)); |
| Element anchor = doc.createElement(ANCHOR); |
| Element block = doc.createElement(DIVISION); |
| |
| parent.appendChild(header); |
| anchor.setAttribute(NAME, text); |
| header.appendChild(anchor); |
| header.appendChild(textNode); |
| parent.appendChild(block); |
| |
| return block; |
| } |
| |
| /** |
| * Wraps the text content of the given node inside a div tag. |
| * |
| * @param node node currently containing the text |
| * @return The new div-element which has been appended to {@code node}. |
| * @throws DOMException |
| */ |
| private static Element wrapTextContentInDiv(Element node) |
| throws DOMException { |
| Document doc = node.getOwnerDocument(); |
| Element div = doc.createElement(DIVISION); |
| div.setTextContent(node.getTextContent()); |
| node.setTextContent(""); |
| node.appendChild(div); |
| return div; |
| } |
| |
| /** |
| * Sets/overwrites the specified attribute. |
| * |
| * @param node target node |
| * @param name attribute name |
| * @param value attribute value |
| * @throws DOMException |
| */ |
| private static void setAttribute(Element node, String name, String value) |
| throws DOMException { |
| Node attr = node.getOwnerDocument().createAttribute(name); |
| attr.setNodeValue(value); |
| |
| node.getAttributes().setNamedItem(attr); |
| } |
| |
| /** |
| * Create an html text element. |
| * @param doc |
| * @param tag |
| * @param text |
| * @return created text Element |
| * @throws Exception |
| */ |
| public static Element createTextElement(Document doc, String tag, |
| String text) throws Exception { |
| Element retval = doc.createElement(tag); |
| Text textNode = doc.createTextNode(text); |
| |
| retval.appendChild(textNode); |
| |
| return retval; |
| } |
| |
| /** |
| * Create a standard link to a local label. |
| * @param doc |
| * @param anchor |
| * @param text |
| * @return created link Element |
| * @throws Exception |
| */ |
| public static Element createLocalLink(Document doc, String anchor, |
| String text) throws Exception { |
| Text textNode = doc.createTextNode(text); |
| |
| return createLocalLink(doc, anchor, textNode); |
| } |
| |
| /** |
| * Create a standard link to a local label. |
| * @param doc |
| * @param anchor |
| * @param visibleText |
| * @return created link Element |
| * @throws Exception |
| */ |
| public static Element createLocalLink(Document doc, String anchor, |
| Node visibleText) throws Exception { |
| return createLink(doc, "#" + anchor, visibleText); |
| } |
| |
| /** |
| * Create a hotlink. |
| * @param doc |
| * @param label |
| * @param text |
| * @return created link Element |
| * @throws Exception |
| */ |
| public static Element createLink(Document doc, String label, String text) |
| throws Exception { |
| Text textNode = doc.createTextNode(text); |
| |
| return createLink(doc, label, textNode); |
| } |
| |
| /** |
| * Create a hotlink. |
| * @param doc |
| * @param label |
| * @param visibleText |
| * @return created anchor Element |
| * @throws Exception |
| */ |
| public static Element createLink(Document doc, String label, |
| Node visibleText) throws Exception { |
| Element hotlink = doc.createElement(ANCHOR); |
| |
| hotlink.setAttribute("href", label); |
| hotlink.appendChild(visibleText); |
| |
| return hotlink; |
| } |
| |
| /** |
| * Insert a list at the end of the parent element. |
| * @param parent |
| * @return created list Element |
| * @throws Exception |
| */ |
| public static Element createList(Element parent) |
| throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Element list = doc.createElement(LIST); |
| |
| parent.appendChild(list); |
| |
| return list; |
| } |
| |
| /** |
| * Add an item with a bold name to the end of a list. |
| * @param list |
| * @param headline |
| * @param text |
| * @return created headline Element |
| * @throws Exception |
| */ |
| public static Element addHeadlinedItem(Element list, String headline, |
| String text) throws Exception { |
| Document doc = list.getOwnerDocument(); |
| Element itemElement = doc.createElement(LIST_ELEMENT); |
| Element boldText = boldText(doc, headline); |
| Text textNode = doc.createTextNode(" - " + text); |
| |
| list.appendChild(itemElement); |
| itemElement.appendChild(boldText); |
| itemElement.appendChild(textNode); |
| |
| return itemElement; |
| } |
| |
| /** |
| * Make some bold text. |
| * @param doc |
| * @param text |
| * @return created bold Element |
| * @throws Exception |
| */ |
| public static Element boldText(Document doc, String text) |
| throws Exception { |
| Element bold = createTextElement(doc, BOLD, text); |
| |
| return bold; |
| } |
| |
| /** |
| * Add an item to the end of a list. |
| * @param list |
| * @param item |
| * @return created item Element |
| * @throws Exception |
| */ |
| public static Element addListItem(Element list, Node item) |
| throws Exception { |
| Document doc = list.getOwnerDocument(); |
| Element itemElement = doc.createElement(LIST_ELEMENT); |
| |
| list.appendChild(itemElement); |
| itemElement.appendChild(item); |
| |
| return itemElement; |
| } |
| |
| /** |
| * Retrieve the indented block inside a section |
| * @param doc |
| * @param sectionLevel |
| * @param sectionName |
| * @return indented block Element |
| * @throws Exception |
| */ |
| public static Element getSection(Document doc, int sectionLevel, |
| String sectionName) throws Exception { |
| String headerTag = makeHeaderTag(sectionLevel); |
| Element root = doc.getDocumentElement(); |
| NodeList sectionList = root.getElementsByTagName(headerTag); |
| int count = sectionList.getLength(); |
| |
| for (int i = 0; i < count; i++) { |
| Element section = (Element) sectionList.item(i); |
| Element sectionAnchor = getFirstChild(section, ANCHOR); |
| |
| if (sectionName.equals(sectionAnchor.getAttribute(NAME))) { |
| // the next item after the section header, is the indented block |
| |
| return (Element) section.getNextSibling(); |
| } |
| } |
| |
| return null; |
| } |
| |
| /** |
| * Make the tag for a header, given its level |
| * @param headerLevel |
| * @return header tag at specified level |
| */ |
| public static String makeHeaderTag(int headerLevel) { |
| return "h" + Integer.toString(headerLevel); |
| } |
| |
| /** |
| * Add a paragraph to the end of a parent element. |
| * @param parent |
| * @param text |
| * @return created paragraph Element |
| * @throws Exception |
| */ |
| public static Element addParagraph(Element parent, String text) |
| throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Text textNode = doc.createTextNode(text); |
| Element paragraph = doc.createElement(PARAGRAPH); |
| |
| parent.appendChild(paragraph); |
| paragraph.appendChild(textNode); |
| |
| return paragraph; |
| } |
| |
| /** |
| * Insert a table at the end of the parent element. |
| * @param parent |
| * @param borderWidth |
| * @param columnHeadings |
| * @return created table Element |
| * @throws Exception |
| */ |
| public static Element createTable(Element parent, int borderWidth, |
| String[] columnHeadings) throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Element table = doc.createElement(TABLE); |
| Element headingRow = insertRow(table); |
| |
| parent.appendChild(table); |
| table.setAttribute(BORDER, Integer.toString(borderWidth)); |
| |
| for (String headerText : columnHeadings) { |
| Element headingColumn = insertColumnHeader(headingRow); |
| headingColumn.setTextContent(headerText); |
| } |
| |
| return table; |
| } |
| |
| /** |
| * Sets the width of the first column in the given table. |
| * |
| * @param table target table |
| * @throws DOMException |
| */ |
| protected void fixWidthOfFirstColumn(Element table) |
| throws DOMException { |
| NodeList headers = table.getElementsByTagName(COLUMN_HEADER); |
| // Just fail if someone removes the th-elements. |
| Element th = (Element)headers.item(0); |
| Element div = wrapTextContentInDiv(th); |
| setAttribute(div, "style", "width:110px;"); |
| th.appendChild(div); |
| } |
| |
| /** |
| * Insert a row at the end of a table |
| * @param table |
| * @return created row Element |
| * @throws Exception |
| */ |
| public static Element insertRow(Element table) |
| throws Exception { |
| return insertTableElement(table, ROW); |
| } |
| |
| /** |
| * Insert a column at the end of a row |
| * @param row |
| * @return created column Element |
| * @throws Exception |
| */ |
| public static Element insertColumn(Element row) |
| throws Exception { |
| return insertTableElement(row, COLUMN); |
| } |
| |
| /** |
| * Insert a header column at the end of the row. |
| * @param row |
| * @return Created column Element |
| * @throws DOMException |
| */ |
| public static Element insertColumnHeader(Element row) |
| throws DOMException { |
| return insertTableElement(row, COLUMN_HEADER); |
| } |
| |
| /** |
| * Inserts the specified element to the parent element. |
| * |
| * @param parent enclosing element, typically a table or a row |
| * @param type type of the new element to be inserted, typically a |
| * column value or a row |
| * @return The newly inserted element. |
| * @throws DOMException if modifying the DOM fails |
| */ |
| private static Element insertTableElement(Element parent, String type) |
| throws DOMException { |
| Document doc = parent.getOwnerDocument(); |
| Element newElement = doc.createElement(type); |
| parent.appendChild(newElement); |
| |
| return newElement; |
| } |
| |
| /** |
| * Insert a horizontal line at the end of the parent element. |
| * @param parent |
| * @return created line Element |
| * @throws Exception |
| */ |
| public static Element insertLine(Element parent) |
| throws Exception { |
| Document doc = parent.getOwnerDocument(); |
| Element line = doc.createElement(HORIZONTAL_LINE); |
| |
| parent.appendChild(line); |
| |
| return line; |
| } |
| |
| //////////////////////////////////////////////////////// |
| // |
| // XML MINIONS |
| // |
| //////////////////////////////////////////////////////// |
| /** |
| * Search the tree rooted at <code>node</code> for nodes tagged with |
| * <code>childName</code>. Return the first such node, or throws an |
| * exception if none is found. |
| * @param node the node to search |
| * @param childName name of child node to get |
| * @return first child element |
| * @throws Exception |
| */ |
| public static Element getFirstChild(Element node, String childName) |
| throws Exception { |
| Element retval = getOptionalChild(node, childName); |
| |
| if (retval == null) { |
| throw new BuildException("Could not find child element '" + |
| childName + "' in parent element '" + |
| node.getNodeName() + "'."); |
| } |
| return retval; |
| } |
| |
| /** |
| * Search the tree rooted at <code>node</code> for nodes tagged with |
| * <code>childName</code>. |
| * Return the index'th such node. |
| * @param node parent |
| * @param childName tag name of qualifying child nodes |
| * @param index of child node to return |
| * @return selected child node |
| * @throws java.lang.Exception |
| */ |
| public static Element getNextChild(Element node, String childName, |
| int index) throws Exception { |
| Element retval = (Element) node.getElementsByTagName(childName).item(index); |
| |
| if (retval == null) { |
| throw new BuildException("Could not find child element '" + |
| childName + "' in parent element '" + |
| node.getNodeName() + "'."); |
| } |
| |
| return retval; |
| } |
| |
| /** |
| * Search the tree rooted at <code>node</code> for nodes tagged with |
| * <code>childName</code>. Return the first such node, or null if tag is |
| * not found. |
| * @param node root of subtree |
| * @param childName type of child (tag) to search for |
| * @return corresponding child if it exitsts, null otherwise. |
| * @throws java.lang.Exception |
| */ |
| public static Element getOptionalChild(Element node, String childName) |
| throws Exception { |
| return (Element) node.getElementsByTagName(childName).item(0); |
| } |
| |
| /** |
| * Squeeze the text out of an Element. |
| * @param node with text child |
| * @return String representation of node's first child |
| * @throws java.lang.Exception |
| */ |
| public static String squeezeText(Element node) |
| throws Exception { |
| return node.getFirstChild().getNodeValue(); |
| } |
| |
| /** |
| * Clone all of the children of a source node and add them as children |
| * of a target node. |
| * @param source |
| * @param target |
| * @throws Exception |
| */ |
| public static void cloneChildren(Node source, Node target) |
| throws Exception { |
| Document targetDoc = target.getOwnerDocument(); |
| NodeList sourceChildren = source.getChildNodes(); |
| int count = sourceChildren.getLength(); |
| |
| for (int i = 0; i < count; i++) { |
| Node sourceChild = sourceChildren.item(i); |
| Node targetChild = targetDoc.importNode(sourceChild, true); |
| target.appendChild(targetChild); |
| } |
| } |
| |
| /** |
| * Replace all instances of the tag with the indicated text. |
| * @param doc |
| * @param tag |
| * @param replacementText |
| * @throws Exception |
| */ |
| public static void replaceTag(Document doc, String tag, |
| String replacementText) throws Exception { |
| NodeList sourceChildren = doc.getElementsByTagName(tag); |
| int count = sourceChildren.getLength(); |
| |
| for (int i = 0; i < count; i++) { |
| Node oldChild = sourceChildren.item(i); |
| Node newChild = doc.createTextNode(replacementText); |
| |
| if (oldChild != null) { |
| Node parent = oldChild.getParentNode(); |
| |
| if (parent != null) { |
| parent.insertBefore(newChild, oldChild); |
| } |
| } |
| } |
| |
| for (int i = count - 1; i > -1; i--) { |
| Node oldChild = sourceChildren.item(i); |
| |
| if (oldChild != null) { |
| Node parent = oldChild.getParentNode(); |
| |
| if (parent != null) { |
| parent.removeChild(oldChild); |
| } |
| } |
| } |
| } |
| |
| //////////////////////////////////////////////////////// |
| // |
| // EXCEPTION PROCESSING MINIONS |
| // |
| //////////////////////////////////////////////////////// |
| /** |
| * Format an error for later reporting. |
| * @param text description |
| * @param t execption that occured |
| * @return formatted error with stack trace |
| */ |
| public static String formatError(String text, Throwable t) { |
| return (text + ": " + t.toString() + "\n" + stringifyStackTrace(t)); |
| } |
| |
| /** |
| * Print a stack trace as a string. |
| * @param t exception to dump stack for |
| * @return String containing the stacl trace for the exception |
| */ |
| public static String stringifyStackTrace(Throwable t) { |
| StringWriter sw = new StringWriter(); |
| PrintWriter pw = new PrintWriter(sw, true); |
| |
| t.printStackTrace(pw); |
| pw.flush(); |
| sw.flush(); |
| |
| return sw.toString(); |
| } |
| |
| //////////////////////////////////////////////////////// |
| // |
| // MISC MINIONS |
| // |
| //////////////////////////////////////////////////////// |
| /** |
| * Format a line of text. |
| * @param text the line to format |
| */ |
| protected void println(String text) { |
| if (_invokedByAnt) { |
| log(text, Project.MSG_WARN); |
| } else { |
| System.out.println(text); |
| } |
| } |
| } |
| |
