This is an automated email from the ASF dual-hosted git repository. pottlinger pushed a commit to branch asf-site in repository https://gitbox.apache.org/repos/asf/creadur-site.git
commit 38d7abe8a2152601a09aeb8af391985b287e65a8 Author: P. Ottlinger <[email protected]> AuthorDate: Tue Oct 22 23:45:38 2024 +0200 Preview new docs --- .../apache-rat-core/development/document_name.html | 210 +++++++++ .../development/write_file_processor.html | 203 +++++++++ rat017/apache-rat-core/exclusion_expression.html | 305 +++++++++++++ rat017/architecture.html | 233 ++++++++++ rat017/development/ui/generator.html | 474 +++++++++++++++++++++ rat017/development/ui/options.html | 218 ++++++++++ rat017/development/ui/ui_specific.html | 234 ++++++++++ rat017/development/ui_implementation.html | 223 ++++++++++ 8 files changed, 2100 insertions(+) diff --git a/rat017/apache-rat-core/development/document_name.html b/rat017/apache-rat-core/development/document_name.html new file mode 100644 index 00000000..b9f1ffea --- /dev/null +++ b/rat017/apache-rat-core/development/document_name.html @@ -0,0 +1,210 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/development/document_name.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ Core – Document Names</title> + <link rel="stylesheet" href="../css/maven-base.css" /> + <link rel="stylesheet" href="../css/maven-theme.css" /> + <link rel="stylesheet" href="../css/site.css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +<a href="../index.html" title="Apache Rat™ Core">Apache Rat™ Core</a> > +Document Names + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Parent Project</h5> + <ul> + <li class="none"><a href="../../index.html" title="Apache Creadur Rat">Apache Creadur Rat</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="../project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="../project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="../../development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="../../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>Document Names</h1> +<p>Rat must be able to distinguish files in multiple file systems; most notably Windows® and Linux®. In addition, we want Rat to produce reports that are comparable across the platforms. To achieve these goals the <code>org.apache.rat.document.impl.DocumentName</code> class was developed.</p> +<p>All documents in the Rat system have a base directory. Different UIs will set the base directory differently. For example:</p> +<ul> + +<li>The command line sets the base directory to the directory or archive specified on the command line.</li> +<li>Ant UI sets the base directory to the directory where the <code>build.xml</code> file is located.</li> +<li>Maven UI sets the base directory to the directory where the project is located.</li> +<li>Other UIs may define the base directory as it fits the underlying build system.</li> +</ul> +<p>When reporting a document Rat will report the path from the base directory to the file; the path relative to the base directory.</p> +<p>The <code>DocumentName</code> comprises:</p> +<ul> + +<li><code>name</code>: The fully qualified file name as provided by the underlying file system.</li> +<li><code>baseName</code>: The fully qualified base directory name as provided by the underlying file system.</li> +<li><code>dirSeparator</code>: The directory separator string used by the underlying file system.</li> +<li><code>isCaseSensitive</code>: The case-sensitive flag for the underlying file system.</li> +</ul> +<p>The class <code>DocumentName</code> also provides a static value that identifies the case-sensitivity of the underlying operating system.</p> +<p><code>DocumentName</code> also provides methods to:</p> +<ul> + +<li>Resolve a name: This method takes a path relative to the DocumentName and creates a new DocumentName instance with the same baseName, dirSeparator and case-sensitivity flag is the original DocumentName.</li> +<li>Localize a name: This method returns the path from the baseName to the file. It utilizes the dirSeparator to separate the directories.</li> +<li>Localize with separator: This method returns the path from the baseName to the file but utilizes a specified string as the directory separator.</li> +<li>Short name: This method returns the last segment of the name.</li> +</ul><section> +<h2><a name="Notes"></a>Notes</h2> +<ul> + +<li><code>DocumentName</code> implements +<ul> + +<li><code>equals()</code>,</li> +<li><code>hashCode()</code></li> +<li><code>Comparable<DocumentName></code>.</li> +</ul> +</li> +<li>Base directories within the system are identified with DocumentNames that have the <code>name</code> and <code>baseName</code> set to the same underlying file system value.</li> +</ul></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/apache-rat-core/development/write_file_processor.html b/rat017/apache-rat-core/development/write_file_processor.html new file mode 100644 index 00000000..cf7c0ca0 --- /dev/null +++ b/rat017/apache-rat-core/development/write_file_processor.html @@ -0,0 +1,203 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/development/write_file_processor.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ Core – Writing a new File Processor</title> + <link rel="stylesheet" href="../css/maven-base.css" /> + <link rel="stylesheet" href="../css/maven-theme.css" /> + <link rel="stylesheet" href="../css/site.css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +<a href="../index.html" title="Apache Rat™ Core">Apache Rat™ Core</a> > +Writing a new File Processor + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Parent Project</h5> + <ul> + <li class="none"><a href="../../index.html" title="Apache Creadur Rat">Apache Creadur Rat</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="../project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="../project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="../../development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="../../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>Writing a new File Processor</h1> +<blockquote> +<section> +<h2><a name="Required_Knowledge"></a>Required Knowledge</h2> +<p>Knowledge of the following topics is recommended:</p> +<ul> + +<li><a href="document_name.html">DocumentName</a>: The DocumentName class that is used to identify files.</li> +<li>Rat <a href="../exclusion_expression.html">Exclude Expressions</a>: The expressions that are used to match file names</li> +</ul> +</blockquote> +<p>A FileProcessor is a module that locates files with a specific name in the directory tree and reads from them file patterns that are translated into Rat exclude expressions. These files are normally found in the file directory tree and their restrictions normally only applies to files at the same directory level as the processed file or below. This type of file is implemented by the <code>org.apache.rat.config.exclusion.fileProcessors.DescendingFileProcessor</code>.</p> +<p>The <code>DescendingFileProcessor</code> takes a file name and one or more comment prefixes as in the constructor. The file name is normally a file that is generally hidden on Linux systems like “.gitignore” or “.hgignore”. The <code>DescendingFileProcessor</code> will scan the directories looking for files with the specified name. If one is found it is passed to the <code>process(DocumentName)</code> method which reads the document and returns a list of [...] +<p>Classes that extend the <code>DescendingFileProcessor</code> have two main extension points: <code>modifyEntry(DocumentName, String)</code> and <code>process(DocumentName)</code>.</p></section><section> +<h2><a name="modifyEntry"></a>modifyEntry</h2> +<p>The <code>modifyEntry</code> method accepts the source <code>DocumentName</code> and a non-comment string. It is expected to process the string and return an exclude expression or null if the line does not result in an exclude expression. The default implementation simply returns the string argument.</p> +<p>An example of <code>modifyEntry</code> is found in the <code>BazaarIgnoreProcessor</code> where lines that start with “RE:” are regular expressions and all other lines are standard exclude patterns. The <code>BazaarIgnoreProcessor.modifyEntry</code> method converts “RE:” prefixed strings into the standard exclude regular expression string.</p></section><section> +<h2><a name="process"></a>process</h2> +<p>In many cases the process method does not need to be modified. In general the process method:</p> +<ul> + +<li>Opens a File on the <code>DocumentName</code></li> +<li>Reads each line in the file</li> +<li>Calls the modifyEntry on the line.</li> +<li>if the line is not null: +<ul> + +<li>Uses the <code>FileProcessor.localizePattern()</code> to create a DocumentName for the pattern with the baseName specified as the name of the file being read.</li> +<li>Stores the new document name in the list of names being returned.</li> +</ul> +</li> +<li>Repeats until all the lines in the input file have been read.</li> +</ul> +<p>Classes that override the <code>process</code> method generally do so because they have some special cases. For example the <code>GitFileProcessor</code> has some specific rules about when to add wildcard paths and when the paths are literal So a special process is required.</p></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/apache-rat-core/exclusion_expression.html b/rat017/apache-rat-core/exclusion_expression.html new file mode 100644 index 00000000..52debb36 --- /dev/null +++ b/rat017/apache-rat-core/exclusion_expression.html @@ -0,0 +1,305 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/exclusion_expression.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ Core – Rat Exclusion Expressions</title> + <link rel="stylesheet" href="./css/maven-base.css" /> + <link rel="stylesheet" href="./css/maven-theme.css" /> + <link rel="stylesheet" href="./css/site.css" /> + <link rel="stylesheet" href="./css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +<a href="index.html" title="Apache Rat™ Core">Apache Rat™ Core</a> > +Rat Exclusion Expressions + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Parent Project</h5> + <ul> + <li class="none"><a href="../index.html" title="Apache Creadur Rat">Apache Creadur Rat</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="../development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>Rat Exclusion Expressions</h1> +<p>Rat uses a variation on the Ant or Git exclusion syntax.</p> +<ul> + +<li><code>?</code> matches a single character. For example ‘ca?’ will match ‘cat’ and ‘can’ but not ‘call’ or the abbreviation for california (or Canada) ‘CA’.</li> +<li><code>*</code> matches zero or more characters. For example ‘ca*’ will match ‘cat’, ‘can’, ‘call’ and the abbreviation for california (or Canada) ‘CA’.</li> +<li><code>**</code> matches zero or more directories. For example ‘**/ca?’ will match ‘my/cat’, ‘my/can’, ‘the/cat’, ‘the/can’, ‘cat’ and ‘can’.</li> +<li><code>!</code> reverses the meaning of the expression. Example “!ca?” will not match “cat” or “can”. See include/exclude notes below.</li> +</ul> +<p>The table below shows an example of how the <code>*</code> and <code>**</code> differ and interact.</p> +<table border="0" class="bodyTable"> +<thead> + +<tr class="a"> +<th align="center"> </th> +<th align="center"><code>foo/x/y</code></th> +<th align="center"><code>b/foo</code></th> +<th align="center"><code>b/foo/x</code></th> +<th align="center"><code>a/b/foo</code></th> +<th align="center"><code>foo</code></th> +<th align="center"><code>a/b/foo/x/y</code></th> +<th align="center"><code>a/b/foo/x</code></th> +<th align="center"><code>foo/x</code></th> +<th align="center"><code>b/foo/x/y</code></th></tr> +</thead><tbody> + +<tr class="b"> +<td align="left"><code>foo</code></td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td></tr> +<tr class="a"> +<td align="left"><code>foo/*</code></td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td></tr> +<tr class="b"> +<td align="left"><code>foo/**</code></td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td></tr> +<tr class="a"> +<td align="left"><code>*/foo</code></td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td></tr> +<tr class="b"> +<td align="left"><code>*/foo/*</code></td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td></tr> +<tr class="a"> +<td align="left"><code>*/foo/**</code></td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td></tr> +<tr class="b"> +<td align="left"><code>**/foo</code></td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td></tr> +<tr class="a"> +<td align="left"><code>**/foo/*</code></td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">F</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">F</td></tr> +<tr class="b"> +<td align="left"><code>**/foo/**</code></td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td> +<td align="center">T</td></tr> +</tbody> +</table><section> +<h2><a name="Inclusion.2FExclusion_Notes"></a>Inclusion/Exclusion Notes</h2> +<p>Patterns that are excluded may be superseded by patterns that are included.</p> +<p>For example: the exclusion pattern ‘ca*’ used in conjunction with the include ‘cat’ would result in the file ‘cat’ being included but ‘can’, ‘call’ and the abbreviation for california (or Canada) ‘CA’ being excluded.</p> +<p>When processed a negated exclusion results in an inclusion, and a negated inclusion results in an exclusion.</p> +<p><b>Once a file is explicitly included it can not be excluded.</b></p></section><section> +<h2><a name="Directory_separation_characters"></a>Directory separation characters</h2> +<p>Patterns may use either ‘/’ or ‘\’ as the path separation character. ‘/’ is recommended.</p></section><section> +<h2><a name="Case_sensitivity"></a>Case sensitivity</h2> +<p>The case sensitivity of the matching patterns depends upon the file system in use. If the file is case-sensitive then the matches are case-sensitive.</p></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/architecture.html b/rat017/architecture.html new file mode 100644 index 00000000..9e7fcc9e --- /dev/null +++ b/rat017/architecture.html @@ -0,0 +1,233 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/architecture.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ – Overview</title> + <link rel="stylesheet" href="./css/maven-base.css" /> + <link rel="stylesheet" href="./css/maven-theme.css" /> + <link rel="stylesheet" href="./css/site.css" /> + <link rel="stylesheet" href="./css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +Overview + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><strong>Architecture</strong></li> + <li class="none"><a href="apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <h5>Modules</h5> + <ul> + <li class="none"><a href="apache-rat-core/index.html" title="Apache Creadur Rat::Core">Apache Creadur Rat::Core</a></li> + <li class="none"><a href="apache-rat-plugin/index.html" title="Apache Creadur Rat::Plugin4Maven">Apache Creadur Rat::Plugin4Maven</a></li> + <li class="none"><a href="apache-rat-tasks/index.html" title="Apache Creadur Rat::Tasks4Ant">Apache Creadur Rat::Tasks4Ant</a></li> + <li class="none"><a href="apache-rat/index.html" title="Apache Creadur Rat::Packaging">Apache Creadur Rat::Packaging</a></li> + <li class="none"><a href="apache-rat-tools/index.html" title="Apache Creadur Rat::Tools">Apache Creadur Rat::Tools</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>Overview</h1> +<p>The RAT architecture is build around a single engine that parses input files to build an XML based report. User interfaces (UIs) create and configure a <code>ReportConfiguration</code> which is passed to a <code>Reporter</code> instance which performs all the processing.</p> + +<div class="source"> +<pre><code>/------\ /------\ /------\ +| CLI | |Maven | | Ant | +| UI | | UI | | UI | +\--+---/ \--+---/ \--+---/ + | | | + \-----------+-----------/ ReportConfiguration + | input to Reporter + /----+----\ + | Reporter| <--- Multiple files and directories + \----+----/ + | + V + Report + +</code></pre></div> +<h1>Configuration</h1> +<p>The <code>ReportConfiguration</code> contains all the options for the Reporter class. User interfaces create a <code>ReportConfiguration</code> and pass it to the <code>Reporter</code> instance for execution. The configuraiton specifies the configuraiton for:</p> +<ul> + +<li>License Families – An identifier for families of licenses that share the same constraints. The default list is defined in the <code>o.a.r.default.xml</code> file in the families section.</li> +<li>Licenses – the definition of a license that defines the matchers that comprise the test for the license. The default licenses are defined in the <code>o.a.r.default.xml</code> file in the licenses section.</li> +<li>Approved License Families – A list of license families that are approved. Licenses of families not in this are unapproved. The defualt approved license families are defined in the <code>o.a.r.default.xml</code> file in the approved section.</li> +</ul><section> +<h2><a name="License_Families"></a>License Families</h2> +<p>A license family comprises an ID and a name. New families may be added to the <code>o.a.r.default.xml</code> file or programattically from the UI. License family IDs must be unique. Later ID definitions override earlier definitions.</p></section><section> +<h2><a name="License"></a>License</h2> +<p>A license definition comprises a family (identified by its ID), and a matcher. Licenses adopt the ID of their family which may be overridden with an id attribute. Licenses also adopt the name of their family unless it is overridden by a name attribute.</p></section><section> +<h2><a name="Approved_Licenses"></a>Approved Licenses</h2> +<p>The approved licenses are enumerated in a list. Licenses are selected by family and the family ID is specified in the list.</p></section><section> +<h2><a name="Matchers"></a>Matchers</h2> +<p>Matchers are classes that implement specific tests. They are created by builders. The default builders are specified in the <code>o.a.r.default.xml</code> file in the matchers section.</p><section> +<h3><a name="Matcher.Builder"></a>Matcher.Builder</h3> +<p>New matcher builders may be defined within the <code>o.a.r.default.xml</code> file and then used in the license definitions within the file.</p> +<p>Matcher builder class names must be of the form <code><name>Builder</code> where <code><name></code> becomes the name of the matcher and is used in identifying the matcher to use (e.g. as a tag in the License section of the <code>o.a.r.default.xml</code> file). They must also implement the <code>o.a.r.analysis.IHeaderMatcher.Builder</code> interface.</p></section></section><section> +<h2><a name="flags_to_add_licenses_and_copyrights_to_files"></a>flags to add licenses and copyrights to files</h2> +<p>The configuration has a set of options to add licenses and optionally copyright notices to files that do not have them. +The <code>addLicenses</code> option adds the Apache2 license to files that do not have any license specified. +If the <code>copyright</code> text is provided it is also added to the files. +The <code>addLicensesForced</code> modifies the way the licenses are added, by default the licenses are added to new files with name of the old file but a <code>.new</code> extension added. +If <code>addLicensesForced</code> is specified then the files are overwritten.</p></section><section> +<h2><a name="file_name_filter"></a>file name filter</h2> +<p>The file name filter specifies a filter to be used to filter out any files that should not be evaluated.</p></section><section> +<h2><a name="out"></a>out</h2> +<p>The <code>out</code> parameter specifies an <code>OutputStream</code> IOSupplier that is used to create the output stream to write text to. By default, this is the <code>System.out</code> stream.</p></section><section> +<h2><a name="stylesheet"></a>stylesheet</h2> +<p>the <code>styleSheet</code> parameter specifies the <code>InputStream</code> IOSupplier that is used to read the stylesheet that styles the XML output.</p></section><section> +<h2><a name="IReportable"></a>IReportable</h2> +<p>The <code>IReportable</code> parameter identifies the objects that the report should run against. +Implementations of <code>IReportable</code> generally do things like walk directory trees, or archives.</p> +<h1>Reporter</h1> +<p>The reporter uses the <code>ReporterConfiguration</code> to configure the report. It then begins to read the files. +Each file is a <code>Document</code> the reporter determines the Document type and if appropriate reads the header information (50 lines) from the document.</p> +<p>The header information is passed to the licenses. The processing of the file stops when a license is triggered (found) or the end of the header is reached.</p> +<p>The information retrieved is used to create an XML document that may be styled by the defined stylesheet.</p> +<p>The reporter utilizes the <code>RatReport</code> interface to determine what actions to take with the documents. +Currently the <code>RatReport</code> interface is used to define license adding capabilities, report claim aggregation, and multiplexed reports. +Additional capabilities can be implemented by implementing a <code>RatReport</code> and inserting it into the processing chain.</p></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/development/ui/generator.html b/rat017/development/ui/generator.html new file mode 100644 index 00000000..ffae781e --- /dev/null +++ b/rat017/development/ui/generator.html @@ -0,0 +1,474 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/development/ui/generator.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ – The Generator</title> + <link rel="stylesheet" href="../../css/maven-base.css" /> + <link rel="stylesheet" href="../../css/maven-theme.css" /> + <link rel="stylesheet" href="../../css/site.css" /> + <link rel="stylesheet" href="../../css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +The Generator + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="../../development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="../../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <h5>Modules</h5> + <ul> + <li class="none"><a href="../../apache-rat-core/index.html" title="Apache Creadur Rat::Core">Apache Creadur Rat::Core</a></li> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Apache Creadur Rat::Plugin4Maven">Apache Creadur Rat::Plugin4Maven</a></li> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Apache Creadur Rat::Tasks4Ant">Apache Creadur Rat::Tasks4Ant</a></li> + <li class="none"><a href="../../apache-rat/index.html" title="Apache Creadur Rat::Packaging">Apache Creadur Rat::Packaging</a></li> + <li class="none"><a href="../../apache-rat-tools/index.html" title="Apache Creadur Rat::Tools">Apache Creadur Rat::Tools</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="../../project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="../../project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>The Generator</h1> +<blockquote> + +<ul> + +<li> +<blockquote> + +<p>Up: <a href="../ui_implementation.html">UI Implementation</a> +<br /><a href="./options.html">Options</a> | Generator | <a href="./ui_specific.html">UI Specific</a></p> +</blockquote> +</li> +</ul> +</blockquote> +<p>The generator is the bit of code that ties the new UI to the Rat CLI. In this section we will explore how the Rat core module exposes the information necessary to build a valuable new UI. We will be using the Maven tooling code in <code>apache-rat-tools</code> as the basis of the examples in this section. As always, the current code base is the source of truth.</p> +<p>There are two implementations of the Generator concept <code>AntGenerator</code> and <code>MavenGenerator</code>.</p><section> +<h2><a name="The_MavenGenerator"></a>The MavenGenerator</h2> +<p>The <code>MavenGenerator</code> generates the abstract class that is used by the <code>apache-rat-plugin</code> module to process Maven elements that are tied to the CLI options. The class starts with a list map of exceptional CLI Option name to Maven option name conversions. In the code below the legacy “addLicense” option is changed to “add-license” so that the standard conversion to camel case will produce the proper name. There is also a list of opti [...] + +<div class="source"> +<pre><code class="language-java"> /** A mapping of external name to internal name if not standard */ + private static final Map<String, String> RENAME_MAP = new HashMap<>(); + + /** List of CLI Options that are not supported by Maven. */ + private static final List<Option> MAVEN_FILTER_LIST = new ArrayList<>(); + + static { + RENAME_MAP.put("addLicense", "add-license"); + + MAVEN_FILTER_LIST.addAll(Arg.DIR.group().getOptions()); + MAVEN_FILTER_LIST.addAll(Arg.LOG_LEVEL.group().getOptions()); + MAVEN_FILTER_LIST.add(OptionCollection.HELP); + } + + /** + * Filter to remove Options not supported by Maven. + */ + private static final Predicate<Option> MAVEN_FILTER = option -> !(MAVEN_FILTER_LIST.contains(option) || option.getLongOpt() == null); + +</code></pre></div> +<p>The list of MavenOptions (see <a href="./options.html">Options</a>) can then be generated by</p> + +<div class="source"> +<pre><code class="language-java">List<MavenOption> options = OptionCollection.buildOptions().getOptions() + .stream().filter(MAVEN_FILTER) + .map(MavenOption::new).collect(Collectors.toList()); +</code></pre></div> +<p>The <code>MavenGenerator</code> uses a template called “Maven.tpl” that looks like:</p> + +<div class="source"> +<pre><code class="language-java">/* + * 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} + +import org.apache.commons.cli.Option; +import org.apache.commons.lang.StringUtils; +import org.apache.maven.plugin.AbstractMojo; +import org.apache.maven.plugins.annotations.Parameter; +import org.apache.rat.commandline.Arg; +import org.apache.rat.utils.CasedString; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.Objects; +import java.util.stream.Collectors; + +/* DO NOT EDIT - GENERATED FILE */ + +/** + * Generated class to provide Maven support for standard Rat command line options + */ +${class} + + private final static Map<String,String> xlateName = new HashMap<>(); + + private final static List<String> unsupportedArgs = new ArrayList<>(); + + static { +${static} + } + + public static String createName(String longOpt) { + String name = xlateName.get(longOpt); + return name != null ? name : new CasedString(CasedString.StringCase.KEBAB, longOpt).toCase(CasedString.StringCase.CAMEL); + } + + public static List<String> unsupportedArgs() { + return Collections.unmodifiableList(unsupportedArgs); + } + +${commonArgs} + +${constructor} + + + /* GENERATED METHODS */ + + +${methods} +} + +</code></pre></div> +<p>this template contains replaceable sections for :</p> +<ul> + +<li>package: The name of the java package that the generated class belongs to.</li> +<li>class: The line that defines the class for the Maven generated code it reads: <code>public abstract class BaseRatMojo extends AbstractMojo {</code>. Note that the Maven example extends a Maven package class.</li> +<li>static: A section to initialize the static data like the translation name table and the unsupportedArgs list.</li> +<li>commonArgs: A section where the “Args.tpl” is inserted. This section contains the methods for argument manipulation that is common among all the UIs</li> +<li>constructor: The constructor for the class. In the Maven case this is simply <code>protected BaseRatMojo() {}</code>.</li> +<li>methods: A section where the generator will insert the methods that map from the Maven framework into the Rat framework as specified in the “Args.tpl”.</li> +</ul></section><section> +<h2><a name="The_Args_template"></a>The Args template</h2> +<p>The args template defines a number of methods to simplify the interface between an arbitrary UI and the Rat CLI command line format. The template defines a variable called <code>args</code> that is a map of a CLI based argument name to a list of Strings that are the argument values.</p> +<p>In general classes that include this template will call: +<code>setArg</code>, <code>addArg</code>, and/or <code>removeArg</code> to set values in the args structure. Eventually the UI class will call <code>getArgs</code> to generate a command line string to pass to the CLI command line parsing code to create a <code>ReportConfiguration</code> that may be modified before calling <code>Reporter.report()</code></p> + +<div class="source"> +<pre><code class="language-java"> ///////////////////////// Start common Arg manipulation code + + /** + * A map of CLI based arguments to values. + */ + protected final Map<String, List<String>> args = new HashMap<>(); + + /** + * Gets the list of arguments prepared for the CLI code to parse. + * @return the List of arguments for the CLI command line. + */ + protected List<String> args() { + List<String> result = new ArrayList<>(); + for (Map.Entry<String, List<String>> entry : args.entrySet()) { + result.add("--" + entry.getKey()); + result.addAll(entry.getValue().stream().filter(Objects::nonNull).collect(Collectors.toList())); + } + return result; + } + + private String argsKey(Option opt) { + return StringUtils.defaultIfEmpty(opt.getLongOpt(), opt.getKey()); + } + + private boolean validateSet(String key) { + Arg arg = Arg.findArg(key); + if (arg != null) { + Option opt = arg.find(key); + Option main = arg.option(); + if (opt.isDeprecated()) { + args.remove(argsKey(main)); + // deprecated options must be explicitly set so let it go. + return true; + } + // non-deprecated options may have default so ignore it if another option has already been set. + for (Option o : arg.group().getOptions()) { + if (!o.equals(main)) { + if (args.containsKey(argsKey(o))) { + return false; + } + } + } + return true; + } + return false; + } + + /** + * Set a key and value into the argument list. + * Replaces any existing value. + * @param key the key for the map. + * @param value the value to set. + */ + protected void setArg(String key, String value) { + if (validateSet(key)) { + List<String> values = new ArrayList<>(); + values.add(value); + args.put(key, values); + } + } + + /** + * Get the list of values for a key. + * @param key the key for the map. + * @return the list of values for the key or {@code null} if not set. + */ + public List<String> getArg(String key) { + return args.get(key); + } + + /** + * Add values to the key in the argument list. + * If the key does not exist, adds it. + * @param key the key for the map. + * @param value the value to set. + */ + protected void addArg(String key, String[] value) { + if (validateSet(key)) { + List<String> values = args.get(key); + if (values == null) { + values = new ArrayList<>(); + args.put(key, values); + } + values.addAll(Arrays.asList(value)); + } + } + + /** + * Add a value to the key in the argument list. + * If the key does not exist, adds it. + * @param key the key for the map. + * @param value the value to set. + */ + protected void addArg(String key, String value) { + if (validateSet(key)) { + List<String> values = args.get(key); + if (values == null) { + values = new ArrayList<>(); + args.put(key, values); + } + values.add(value); + } + } + + /** + * Remove a key from the argument list. + * @param key the key to remove from the map. + */ + protected void removeArg(String key) { + args.remove(key); + } + + ///////////////////////// End common Arg manipulation code + +</code></pre></div></section><section> +<h2><a name="Generating_Methods"></a>Generating Methods</h2> +<p>For every <code>MavenOption</code> at least one method is created.</p><section> +<h3><a name="Generating_the_method_signature"></a>Generating the method signature</h3> +<p>The <code>MavenGenerator</code> needs to generate method signatures based on the <code>org.apache.commons.cli.Option</code> state so the <code>MavenOption</code> provides the <code>getMethodSignature</code> method. This method checks the following conditions.</p> +<ol style="list-style-type: decimal"> + +<li>Is the option deprecated? If so add the <code>@Deprecated</code> annotation.</li> +<li>Does the option accept one or more arguments (i.e. is not a flag option)? If it does the argument should be a <code>String</code> otherwise it should be a <code>boolean</code>.</li> +<li>Does the method accept multiple arguments? If so modify the name to indicate plural as per the Maven standard.</li> +<li>Create the Maven <code>@Property</code> annotation with optional Maven command line property and defaults for the method.</li> +<li>Write all the information into a string and prefix the method name with “set” as per the Maven standard.</li> +</ol> +<p>With the result being that a fully formed, Maven compliant, Java method signature is developed. Complete with documentation from the Option description. For example “–copyright”, which is a deprecated option, produces the following Maven mojo method signature:</p> + +<div class="source"> +<pre><code class="language-java">/** + * The copyright message to use in the license headers. + * @param copyright copyright message to use in the license headers. + * @deprecated Deprecated for removal since 0.17: Use &lt;editCopyright&gt; instead. + */ + @Deprecated + @Parameter(property = "rat.Copyright") + public void setCopyright(String copyright) { +</code></pre></div></section><section> +<h3><a name="Generating_the_method_body"></a>Generating the method body</h3> +<p>When executing the generated class should take the value passed in from the new UI convert it to a <code>String</code> (or <code>boolean</code> if a flag option) and call the <code>setArg</code> (or possibly the <code>removeArg</code>) method defined in <code>Args.tpl</code>. The key for the arg method is the CLI option name (without leading dashes). In the case of the <code>setCopyright</code> method above this looks like:</p> + +<div class="source"> +<pre><code class="language-java">public void setCopyright(String copyright) { + setArg("copyright", copyright); + } +</code></pre></div> +<p>Maven also supports the case where multiple values are accepted for one Property. To support this the <code>MavenGenerator</code> will generate methods that accept multiple String arguments and have a name that pluralizes the standard “set” based name. Details are available in the <code>MavenGenerator</code> code.</p></section></section><section> +<h2><a name="AntGenerator"></a>AntGenerator</h2> +<p>The AntGenerator follows the same design as the MavenGenerator. The main difference is that Ant allows attributes in the XML elements.</p> +<blockquote> + +<ul> + +<li> +<blockquote> + +<p>Up: <a href="../ui_implementation.html">UI Implementation</a> +> <br /><a href="./options.html">Options</a> | Generator | <a href="./ui_specific.html">UI Specific</a></p> +</blockquote> +</li> +</ul> +</blockquote></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/development/ui/options.html b/rat017/development/ui/options.html new file mode 100644 index 00000000..d80ec0f3 --- /dev/null +++ b/rat017/development/ui/options.html @@ -0,0 +1,218 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/development/ui/options.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ – Options</title> + <link rel="stylesheet" href="../../css/maven-base.css" /> + <link rel="stylesheet" href="../../css/maven-theme.css" /> + <link rel="stylesheet" href="../../css/site.css" /> + <link rel="stylesheet" href="../../css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +Options + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="../../development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="../../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <h5>Modules</h5> + <ul> + <li class="none"><a href="../../apache-rat-core/index.html" title="Apache Creadur Rat::Core">Apache Creadur Rat::Core</a></li> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Apache Creadur Rat::Plugin4Maven">Apache Creadur Rat::Plugin4Maven</a></li> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Apache Creadur Rat::Tasks4Ant">Apache Creadur Rat::Tasks4Ant</a></li> + <li class="none"><a href="../../apache-rat/index.html" title="Apache Creadur Rat::Packaging">Apache Creadur Rat::Packaging</a></li> + <li class="none"><a href="../../apache-rat-tools/index.html" title="Apache Creadur Rat::Tools">Apache Creadur Rat::Tools</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="../../project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="../../project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>Options</h1> +<blockquote> + +<p>Up: <a href="../ui_implementation.html">UI Implementation</a> +<br />Options | <a href="./generator.html">Generator</a> | <a href="./ui_specific.html">UI Specific</a></p> +</blockquote> +<p>In this section we will explore how the Rat core module exposes the information necessary to build a UI specific Option implementation. We will be using the Maven tooling code in <code>apache-rat-tools</code> as the basis of the examples in this section. As always, the current code base is the source of truth.</p> +<p>Rat core uses the Apache Commons CLI library to process command line options. All the options are recorded in the <code>org.apache.rat.commandline.Arg</code> enumeration. Internally the Arg enumeration contains logical option groups that represent a single option. The use of option groups provides us a way to deprecate options and create replacements. Only one option in an option group may be used in a single Rat invocation.</p> +<p>Each UI will have a representation of the individual Options specified within the Arg enumeration. To simplify the code each UI implementation should have an implementation of the <code>org.apache.rat.tools.AbstractOption</code> class. This class will map the information contained in the <code>org.apache.commons.cli.Option</code> into methods that make sense with respect to the UI being implemented.</p> +<p>As an example we will look at the <code>org.apache.rat.tools.MavenOption</code>.</p><section> +<h2><a name="MavenOption"></a>MavenOption</h2><section> +<h3><a name="Name_conversion"></a>Name conversion</h3> +<p>First to deal with the mapping from the kebab style to the camel case style, the <code>MavenOption</code> utilizes a static method in the <code>MavenGenerator</code> class to perform the conversion.</p> + +<div class="source"> +<pre><code class="language-java"> static String createName(final Option option) { + String name = StringUtils.defaultIfEmpty(option.getLongOpt(), option.getOpt()); + name = StringUtils.defaultIfEmpty(RENAME_MAP.get(name), name).toLowerCase(Locale.ROOT); + return new CasedString(StringCase.KEBAB, name).toCase(StringCase.CAMEL); + } +</code></pre></div> +<p>This method ensures that long options are selected over short options and then allows those options to be mapped to a different name. The remapping is an historical case where there was a camel case option in the CLI that had to be converted to kebab case first. In addition, it may be that a future CLI option will generate a camel case name that conflicts with some other UI based method. The mapping allows that to be easily overcome. Finally, the <code>createName</code> method use [...] +<h3><a name="Overridden_methods"></a>Overridden methods</h3> +<p>The AbstractOption has several methods that should be overridden.</p><section> +<h4><a name="cleanupName"></a>cleanupName</h4> +<p>The cleanup name method is called by the AbstractOption to convert the <code>org.apache.commons.cli.Option</code> name (kabob style) into the name expected in the configuration of the UI. In the Maven case it returns the camel case name inside of angle brackets so that it appears as an XML element name.</p></section><section> +<h4><a name="getDefaultValue"></a>getDefaultValue</h4> +<p>The default value method will return the default value specified in the <code>org.apache.commons.cli.Option</code> unless it is overridden.</p> +<p>Maven allows the definition of default values for its options. The class <code>org.apache.rat.tools.MavenOption</code> defines the default values for the CLI options that have default values in Maven. For example, the Maven environment expects the output of the tool to be written to a file and not displayed on standard out so this value is set as the default.</p></section></section><section> +<h3><a name="Generating_the_method_signature"></a>Generating the method signature</h3> +<p>The MavenGenerator needs to generate method signatures based on the <code>org.apache.commons.cli.Option</code> state so the MavenOption provides the <code>getMethodSignature</code> method. This method checks the following conditions.</p> +<ol style="list-style-type: decimal"> + +<li>Is the option deprecated? If so add the <code>@Deprecated</code> annotation.</li> +<li>Does the option accept one or more arguments (i.e. is not a flag option)? If it does the argument should be a <code>String</code> otherwise it should be a <code>boolean</code>.</li> +<li>Does the method accept multiple arguments? If so modify the name to indicate plural as per the Maven standard.</li> +<li>Create the Maven <code>@Property</code> annotation with optional Maven command line property and defaults for the method.</li> +<li>Write all the information into a string and prefix the method name with “set” as per the Maven standard.</li> +</ol></section></section><section> +<h2><a name="AntOption"></a>AntOption</h2> +<p>The <code>AntOption</code> class is very similar to the <code>MavenOption</code> except that, as noted earlier, it creates XML Elements and Attributes depending on whether the option accepts more than one argument.</p> +<blockquote> + +<p>Up: <a href="../ui_implementation.html">UI Implementation</a> +<br />Options | <a href="./generator.html">Generator</a> | <a href="./ui_specific.html">UI Specific</a></p> +</blockquote></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/development/ui/ui_specific.html b/rat017/development/ui/ui_specific.html new file mode 100644 index 00000000..4b81f1fd --- /dev/null +++ b/rat017/development/ui/ui_specific.html @@ -0,0 +1,234 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/development/ui/ui_specific.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ – The UI specific code</title> + <link rel="stylesheet" href="../../css/maven-base.css" /> + <link rel="stylesheet" href="../../css/maven-theme.css" /> + <link rel="stylesheet" href="../../css/site.css" /> + <link rel="stylesheet" href="../../css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +The UI specific code + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><a href="../../development/ui_implementation.html" title="UI Development">UI Development</a></li> + <li class="none"><a href="../../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <h5>Modules</h5> + <ul> + <li class="none"><a href="../../apache-rat-core/index.html" title="Apache Creadur Rat::Core">Apache Creadur Rat::Core</a></li> + <li class="none"><a href="../../apache-rat-plugin/index.html" title="Apache Creadur Rat::Plugin4Maven">Apache Creadur Rat::Plugin4Maven</a></li> + <li class="none"><a href="../../apache-rat-tasks/index.html" title="Apache Creadur Rat::Tasks4Ant">Apache Creadur Rat::Tasks4Ant</a></li> + <li class="none"><a href="../../apache-rat/index.html" title="Apache Creadur Rat::Packaging">Apache Creadur Rat::Packaging</a></li> + <li class="none"><a href="../../apache-rat-tools/index.html" title="Apache Creadur Rat::Tools">Apache Creadur Rat::Tools</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="../../project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="../../project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>The UI specific code</h1> +<blockquote> + +<p>Up: <a href="../ui_implementation.html">UI Implementation</a> +<br /><a href="./options.html">Options</a> | <a href="./generator.html">Generator</a> | UI Specific</p> +</blockquote> +<p>In most cases the UI provides values for some of the CLI options, or have additional options that are not supported by CLI. In the case of Maven there is a “skip” option that causes the Maven plugin to not execute. This is not implemented in the CLI as it is assumed if you don't want to execute the CLI you won't call it.</p> +<p>The <code>apache-rat-plugin</code> contains the code for the Maven UI extension. In this particular case there are three components that extend the generated abstract class.</p> +<ol style="list-style-type: decimal"> + +<li><code>AbstractRatMojo</code> - extends the generated class and add standard functionality.</li> +<li><code>RatCheckMojo</code> - extends <code>AbstractRatMojo</code> and adds the functionality to execute the Rat core <code>Reporter</code> class.</li> +<li><code>RatReportMojo</code> - extends <code>AbstractRatMojo</code> and adds the functionality to provide reports into the Maven reporting system.</li> +</ol><section> +<h2><a name="Added_.2F_Modified_functionality"></a>Added / Modified functionality</h2><section> +<h3><a name="Logging"></a>Logging</h3> +<p>Most UIs have some process for logging. Rat defines a <a class="externalLink" href="https://github.com/apache/creadur-rat/blob/master/apache-rat-core/src/main/java/org/apache/rat/utils/Log.java";>Log</a> interface and uses the <a class="externalLink" href="https://github.com/apache/creadur-rat/blob/master/apache-rat-core/src/main/java/org/apache/rat/utils/DefaultLog.java";>DefaultLog</a> class to track the instance.</p> +<p>The <code>AbstractRatMojo</code> class has a <code>makeLog</code> method that wraps the Maven log to create an instance of the Rat Log interface. In the <code>getConfiguration</code> method the DefaultLog default is set to return the wrapped Maven log.</p></section><section> +<h3><a name="Processing_Arguments"></a>Processing Arguments</h3> +<p>the <code>AbstractRatMojo.getConfiguration</code> performs some changes to the args defined in generated base class, generates the configuration and then calls:</p> + +<div class="source"> +<pre><code class="language-java">ReportConfiguration config = OptionCollection.parseCommands(args().toArray(new String[0]), + o -> getLog().warn("Help option not supported"), + true); +</code></pre></div> +<p>The above line creates the configuration from the args and if the user somehow manages to call help will log a warning that help is not supported.</p> +<p>After the <code>ReportConfiguration</code> is created it is modified based on specific Maven command line options before it is returned to the calling method.</p></section></section><section> +<h2><a name="Executing_the_Rat_scan.2A.2A.2A.2A"></a>Executing the Rat scan****</h2> +<p>The Maven code executes the Rat scan in the <code>RatCheckMojo.execute()</code> method. This method processes the Maven “skip” option, checks is the output is overridden in the Args structure and if not sets the Maven default, retrieves the configuration and executes:</p> + +<div class="source"> +<pre><code class="language-java">try { + this.reporter = new Reporter(config); + reporter.output(); + check(); +} catch (MojoFailureException e) { + throw e; +} catch (Exception e) { + throw new MojoExecutionException(e.getMessage(), e); +} +</code></pre></div> +<p>The <code>check()</code> method performs custom checks and logging for Maven specific issues.</p></section><section> +<h2><a name="Ant_processing"></a>Ant processing</h2> +<p>The Ant processing is performed by the <code>Report</code> class in the <code>apache-rat-tasks</code> module. It follows the same basic processing path as the Maven processing except that it handle Ant specific requirements and options. The class has an <code>execute()</code> method that looks very similar to the Maven version:</p> + +<div class="source"> +<pre><code class="language-java">try { + Reporter r = new Reporter(validate(getConfiguration())); + r.output(StyleSheets.PLAIN.getStyleSheet(), () -> new ReportConfiguration.NoCloseOutputStream(System.out)); + r.output(); +} catch (BuildException e) { + throw e; +} catch (Exception ioex) { + throw new BuildException(ioex); +} +</code></pre></div> +<blockquote> + +<p>Up: <a href="../ui_implementation.html">UI Implementation</a> +<br /><a href="./options.html">Options</a> | <a href="./generator.html">Generator</a> | UI Specific</p> +</blockquote></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html> diff --git a/rat017/development/ui_implementation.html b/rat017/development/ui_implementation.html new file mode 100644 index 00000000..7406e351 --- /dev/null +++ b/rat017/development/ui_implementation.html @@ -0,0 +1,223 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/development/ui_implementation.md at 2024-10-22 + + | Rendered using Apache Maven Default Skin +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> + <title>Apache Rat™ – UI Development</title> + <link rel="stylesheet" href="../css/maven-base.css" /> + <link rel="stylesheet" href="../css/maven-theme.css" /> + <link rel="stylesheet" href="../css/site.css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> +<link href="https://creadur.apache.org/font/matesc.css"; type="text/css" rel="stylesheet" /> + </head> + <body class="composite"> + <div id="banner"> +<a href="https://www.apache.org/"; id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png"; alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear"> + <hr/> + </div> + </div> + <div id="breadcrumbs"> + <div class="xleft"> + <span id="publishDate">Last Published: 2024-10-22</span> + | <span id="projectVersion">Version: 0.17-SNAPSHOT</span> + | <a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a> > +<a href="https://creadur.apache.org/"; class="externalLink" title="Creadur">Creadur</a> > +<a href="https://creadur.apache.org/rat/"; class="externalLink" title="Rat">Rat</a> > +UI Development + </div> + <div class="xright"> </div> + <div class="clear"> + <hr/> + </div> + </div> + <div id="leftColumn"> + <div id="navcolumn"> + <h5>Apache Rat™</h5> + <ul> + <li class="none"><a href="../index.html" title="Introducing Rat">Introducing Rat</a></li> + <li class="none"><a href="../download_rat.cgi" title="Downloads">Downloads</a></li> + <li class="none"><a href="../RELEASE_NOTES.txt" title="Changes">Changes</a></li> + </ul> + <h5>Rat from the Command Line</h5> + <ul> + <li class="none"><a href="../apache-rat/index.html" title="Command Line Introduction">Command Line Introduction</a></li> + <li class="none"><a href="../apache-rat-core/exclusion_expression.html" title="Exclusion Expressions">Exclusion Expressions</a></li> + </ul> + <h5>Rat from Ant</h5> + <ul> + <li class="none"><a href="../apache-rat-tasks/index.html" title="Ant Task Introduction">Ant Task Introduction</a></li> + </ul> + <h5>Rat from Maven</h5> + <ul> + <li class="none"><a href="../apache-rat-plugin/index.html" title="Maven Plugin Introduction">Maven Plugin Introduction</a></li> + </ul> + <h5>Configuring Rat</h5> + <ul> + <li class="none"><a href="../license_def.html" title="Defining New Licenses">Defining New Licenses</a></li> + <li class="none"><a href="../apache-rat/name_xref.html" title="Option Name Cross Reference">Option Name Cross Reference</a></li> + <li class="none"><a href="../apache-rat/default_licenses.html" title="Default Licenses, etc">Default Licenses, etc</a></li> + <li class="none"><a href="../apache-rat/xsd.html" title="Configuration XSD">Configuration XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml"; class="externalLink" title="Default Configuration">Default Configuration</a></li> + </ul> + <h5>Rat Output</h5> + <ul> + <li class="none"><a href="../apache-rat/output/example.html" title="Standard Output Example">Standard Output Example</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd"; class="externalLink" title="Output XSD">Output XSD</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl"; class="externalLink" title="XSLT - Plain text">XSLT - Plain text</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl"; class="externalLink" title="XSLT - Missing headers list">XSLT - Missing headers list</a></li> + <li class="none"><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl"; class="externalLink" title="XSLT - Unapproved licenses list">XSLT - Unapproved licenses list</a></li> + </ul> + <h5>Developing Rat</h5> + <ul> + <li class="none"><a href="../architecture.html" title="Architecture">Architecture</a></li> + <li class="none"><a href="../apidocs/index.html" title="Javadocs">Javadocs</a></li> + <li class="none"><a href="../apache-rat-core/development/document_name.html" title="Document Name concept">Document Name concept</a></li> + <li class="none"><strong>UI Development</strong></li> + <li class="none"><a href="../apache-rat-core/development/write_file_processor.html" title="Writing a File Processor">Writing a File Processor</a></li> + </ul> + <h5>Apache Creadur™</h5> + <ul> + <li class="none"><a href="https://creadur.apache.org"; class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li> + <li class="none"><a href="https://creadur.apache.org/tentacles"; class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li> + <li class="none"><a href="https://creadur.apache.org/whisker"; class="externalLink" title="Apache Whisker">Apache Whisker</a></li> + <li class="none"><a href="https://www.apache.org/security/"; class="externalLink" title="Security">Security</a></li> + <li class="none"><a href="https://www.apache.org/licenses/"; class="externalLink" title="License">License</a></li> + <li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html"; class="externalLink" title="Privacy">Privacy</a></li> + <li class="none"><a href="https://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship">Sponsorship</a></li> + <li class="none"><a href="https://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks">Thanks</a></li> + </ul> + <h5>The Apache Software Foundation</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation"; class="externalLink" title="About the Foundation">About the Foundation</a></li> + <li class="none"><a href="https://projects.apache.org"; class="externalLink" title="The projects">The projects</a></li> + <li class="none"><a href="https://people.apache.org"; class="externalLink" title="The people">The people</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html"; class="externalLink" title="How we work">How we work</a></li> + <li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history"; class="externalLink" title="Our history">Our history</a></li> + <li class="none"><a href="https://blogs.apache.org/foundation/"; class="externalLink" title="News">News</a></li> + </ul> + <h5>Contribute</h5> + <ul> + <li class="none"><a href="https://www.apache.org/foundation/getinvolved.html"; class="externalLink" title="Get Involved">Get Involved</a></li> + </ul> + <h5>Committer Info</h5> + <ul> + <li class="none"><a href="https://www.apache.org/dev/committers.html"; class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li> + <li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html"; class="externalLink" title="New Committers Guide">New Committers Guide</a></li> + <li class="none"><a href="../site-publish.html" title="Howto publish this site">Howto publish this site</a></li> + <li class="none"><a href="https://community.apache.org/"; class="externalLink" title="Community">Community</a></li> + <li class="none"><a href="https://www.apache.org/legal/"; class="externalLink" title="Legal">Legal</a></li> + <li class="none"><a href="https://www.apache.org/foundation/marks/"; class="externalLink" title="Branding">Branding</a></li> + <li class="none"><a href="https://www.apache.org/press/"; class="externalLink" title="Media Relations">Media Relations</a></li> + </ul> + <h5>Modules</h5> + <ul> + <li class="none"><a href="../apache-rat-core/index.html" title="Apache Creadur Rat::Core">Apache Creadur Rat::Core</a></li> + <li class="none"><a href="../apache-rat-plugin/index.html" title="Apache Creadur Rat::Plugin4Maven">Apache Creadur Rat::Plugin4Maven</a></li> + <li class="none"><a href="../apache-rat-tasks/index.html" title="Apache Creadur Rat::Tasks4Ant">Apache Creadur Rat::Tasks4Ant</a></li> + <li class="none"><a href="../apache-rat/index.html" title="Apache Creadur Rat::Packaging">Apache Creadur Rat::Packaging</a></li> + <li class="none"><a href="../apache-rat-tools/index.html" title="Apache Creadur Rat::Tools">Apache Creadur Rat::Tools</a></li> + </ul> + <h5>Project Documentation</h5> + <ul> + <li class="collapsed"><a href="../project-info.html" title="Project Information">Project Information</a></li> + <li class="collapsed"><a href="../project-reports.html" title="Project Reports">Project Reports</a></li> + </ul> + <a href="https://maven.apache.org/"; title="Maven" class="poweredBy"> + <img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png"; /> + </a> + </div> + </div> + <div id="bodyColumn"> + <div id="contentBox"> +<!--- + 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. +--> +<h1>UI Development</h1><section> +<h2><a name="Overview"></a>Overview</h2> +<p>The Rat architecture supports multiple UIs. By default, Rat provides a command line implementation (CLI) as well as implementations for the Ant and Maven build system. The source code for those implementation provide a good roadmap for implementing any new UI.</p><section> +<h3><a name="CLI_first"></a>CLI first</h3> +<p>Rat is designed as a CLI first architecture. This means that every new functionality is introduced as a CLI option first. All tests cases are built and the implementation verified before it is released. Additional native UIs are build on top of the CLI implementation.</p> +<p>For example the CLI uses kabob format options (e.g. –this-is-an-option) Ant and Maven use an XML format configuration utilizing camel case names. For Maven all options are elements in the Maven <code>pom.xml</code> file, for Ant it is a bit more complicated because Ant allows for attributes for elements while maven does not.</p> +<p>In the Maven example Rat is defined as a plugin. We expect the new <code>--this-is-an-option</code> option to be reflected in that section as <code><thisIsAnOption></code>. So expect to see something like</p> + +<div class="source"> +<pre><code class="language-xml"><plugin> + <groupId>org.apache.rat</groupId> + <artifactId>apache-rat-plugin</artifactId> + <configuration> + <thisIsAnOption>option value</thisIsAnOption> + <!-- more options here --> + </configuration> +</plugin> +</code></pre></div> +<p>For Ant the new option may be a child element of the <code><rat:report></code> element, if the option only has a single argument it may be an attribute of the <code><rat:report></code> element. Therefor, we expect to see either</p> + +<div class="source"> +<pre><code class="language-xml"><rat:report thisIsAnOption='option value'> + <!-- more options here --> +</rat:report> +</code></pre></div> +<p>or</p> + +<div class="source"> +<pre><code class="language-xml"><rat:report> + <rat:thisIsAnOption>option value</rat:thisIsAnOption> + <!-- more options here --> +</rat:report> +</code></pre></div> +<p>Note that if <code>--this-is-an-option</code> is a flag then the elements would be closed without text and the And attribute would be <code>thisIsAnOption='true'</code>.</p></section><section> +<h3><a name="UI_adapter_architecture"></a>UI adapter architecture</h3> +<p>The UIs are actually implemented as adapters. They plug into an existing system and provide a mechanism to call the CLI code. They utilize classes in the <code>apache-rat-tools</code> module that map from the CLI options into the UI options.</p> +<p>The basic build operation for a UI adapter is:</p> +<ol style="list-style-type: decimal"> + +<li>Execute a “Generator” to produce a base class for the UI based on the definitions found in the Rat core classes.</li> +<li>Compile the UI specific code that extends the generated base class.</li> +<li>Package the UI specific code in a manner expected by the UI being extended.</li> +</ol><section> +<h4><a name="The_Options"></a><a href="ui/options.html">The Options</a></h4> +<p>Each UI has specific requirements to display and accept input for the CLI options. In most cases it makes sense to create a UI Specific Option that takes the CLI option as a constructor argument and creates an Option that is used by the Generator and other associated code.</p></section><section> +<h4><a name="The_Generator"></a><a href="ui/generator.html">The Generator</a></h4> +<p>The Generator class literally writes the source code for the base of the UI adapter. The adapter accepts input from the new UI and converts the UI option into the kebab format for the CLI and places the values associated with that option into a Map indexed by the CLI option name. In our example above both the Ant and the Maven UI would take the value for <code>thisIsAnOption</code> and place the values into the map as <code>this-is-an-option</code>.</p> +<p>The Options in the CLI have sufficient information for the Generator to provide user documentation for the methods in a form acceptable to the new UI ecosystem.</p> +<p>The class created by the Generator should have methods that represent all the options in the CLI. In most cases there is a one-to-one correspondence between a method in the base class and the options in the CLI.</p></section><section> +<h4><a name="UI_specific_code"></a><a href="ui/ui_specific.html">UI specific code</a></h4> +<p>The UI specific code uses extends the class created by the Generator and adds additional UI specific options and generally performs the necessary options to hook the new UI into the system being supported. Examples of this type of code can be found in the <code>apache-rat-tasks</code> (Ant) and <code>apache-rat-plugin</code> (Maven) modules.</p></section></section></section> + </div> + </div> + <div class="clear"> + <hr/> + </div> + <div id="footer"> + <div class="xright"> + Copyright © 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. + Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks + of The Apache Software Foundation. + Oracle and Java are registered trademarks of Oracle and/or its affiliates. + All other marks mentioned may be trademarks or registered trademarks of their respective owners. + </div> + <div class="clear"> + <hr/> + </div> + </div> + </body> +</html>
![https://www.apache.org/img/asf_logo.png"](https://www.apache.org/img/asf_logo.png"){kind=link}
![https://maven.apache.org/images/logos/maven-feather.png"](https://maven.apache.org/images/logos/maven-feather.png"){kind=link}