/*
 * [Possibility.java]
 *
 * Summary: types of links to Oracle website.
 *
 * Copyright: (c) 2017 Roedy Green, Canadian Mind Products, http://mindprod.com
 *
 * Licence: This software may be copied and used freely for any purpose but military.
 *          http://mindprod.com/contact/nonmil.html
 *
 * Requires: JDK 1.8+
 *
 * Created with: JetBrains IntelliJ IDEA IDE http://www.jetbrains.com/idea/
 *
 * Version History:
 *  1.0 2017-03-23 initial vers
 */
package com.mindprod.htmlmacros.macro;

import com.mindprod.common18.Misc;
import com.mindprod.common18.ST;
import com.mindprod.fastcat.FastCat;
import com.mindprod.htmlmacros.support.JDKandJREVersions;
import com.mindprod.htmlmacros.support.Tools;

import java.io.File;

import static com.mindprod.htmlmacros.macro.OnOracle.ORACLES;
import static com.mindprod.htmlmacros.support.JDKandJREVersions.*;

/**
 * types of links to Oracle website.
 *
 * @author Roedy Green, Canadian Mind Products
 * @version 1.0 2017-03-23 initial vers
 * @since 2017-03-23
 */
enum Possibility
    {
        BROKEN( "broken" /* was http://www.oracle.com/technetwork/java/index.html */ )
                    {
                    String elaborate( final String ref, final String desc )
                        {
                        return "Sun-composed " +
                               "material on " + bold( desc );
                        }

                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildBrokenLink( elaborate( ref, desc ), notes );
                        }
                    },
        TRAINING( "http://education.oracle.com" )
                    {
                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Developer Online Training on " + bold(
                                desc );
                        }
                    },
        DEVELOPER( "http://www.oracle.com/technetwork/developer-tools/" )
                    {
                    // typical http://java.sun.com/developer/onlineTraining/corba/

                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Developer Documentation on "
                               + bold( desc );
                        }
                    },
        J2EE( "http://www.oracle.com/us/technologies/java/enterprise-edition" )
                    {
                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        Acronym acronym = new Acronym();
                        acronym.setFileBeingProcessedAndFileBeingDistributed( fileBeingProcessed,
                                fileBeingDistributed );
                        return ORACLES + acronym.expandNoRef( "EE" ) + " docs on " + bold( desc );
                        }
                    },
        JAVA14( "https://docs.oracle.com/javase/1.4" )
                    {
                    // typical http://docs.oracle.com/javase/1.4.2/docs/guide/lang/assert.html#usage-invariants

                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "older Java 1.4 documentation on : "
                               + bold( desc );
                        }
                    },
        JAVA15( "https://docs.oracle.com/javase/1.5.0/" )
                    {
                    // typical  http://docs.oracle.com/javase/1.5.0/docs/guide/javaws/developersguide/cdinstall.03.06
                    // .html

                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Discontinued Java 1.5 documentation on : "
                               + bold( desc );
                        }
                    },
        JAVA6( "https://docs.oracle.com/javase/6/" )
                    {
                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Discontinued Java 1.6 documentation on : "
                               + bold( desc );
                        }
                    },
        JAVA7( "https://docs.oracle.com/javase/7/" )
                    {
                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Previous Java 1.7 documentation on : "
                               + bold( desc );
                        }
                    },
        JAVA8( "https://docs.oracle.com/javase/8/" )
                    {
                    /**
                     * guts to Generate reference to a Oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Java 1.8 documentation on : "
                               + bold( desc );
                        }
                    },
        JAVAAPI( JDKandJREVersions.ORACLE_JAVA_SE + "docs/api/" )
                    {
                    // we don't handle this here. Use JavaAPI
                    // typical http://docs.oracle.com/javase/" + JDKandJREVersions.ORACLE_JAVA_SE + "/docs/api/java/awt/Robot.html#keyPress(int)

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Java 1.8 api docs : " + bold( desc );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     *   @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        if ( ref.contains( "-" ) )
                            {
                            // link into a non Class description buried in the API docs.
                            return buildDualLink( ref, elaborate( ref, desc ), notes );
                            }
                        else
                            {
                            throw new IllegalArgumentException( "Error: OnOracle  {" + ref + "} should be handled with" +
                                                                " the JavaAPI macro" );
                            }
                        }
                    },
        JLS( "https://docs.oracle.com/javase/specs/" )
                    {
                    // typical {http://docs.oracle.com/javase/specs/jls/se8/html/jls-15.html#15.7} "expression
                    // evaluation order"

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     *
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        if ( ref.contains( "se7" ) )
                            {
                            throw new IllegalArgumentException( "obsolete JLS reference: " + ref );
                            }
                        Acronym acronym = new Acronym();
                        acronym.setFileBeingProcessedAndFileBeingDistributed( fileBeingProcessed,
                                fileBeingDistributed );
                        return acronym.expandNoRef( "JLS" ) + ": " + bold( desc );
                        }
                    },
        JDK( JDKandJREVersions.ORACLE_JAVA_SE + "docs/jdk/" )
                    {
                    // typical http://docs.oracle.com/javase/" + JDKandJREVersions.oracle + "/docs/technotes/guides/net/proxies.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildDualLink( ref, elaborate( ref, desc ), notes );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "JDK Guide to " + bold( desc );
                        }
                    },
        JWS( JDKandJREVersions.ORACLE_JAVA_SE + "docs/jre/api/javaws/jnlp" )
                    {
                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildDualLink( ref, elaborate( ref, desc ), notes );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "JWS api for " + bold( desc );
                        }
                    },
        JRE( JDKandJREVersions.ORACLE_JAVA_SE + "docs/jre/" )
                    {
                    // typical http://docs.oracle.com/javase/" + JDKandJREVersions.oracle + "/docs/jre/api/plugin/dom/index.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildDualLink( ref, elaborate( ref, desc ), notes );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "JRE Guide to " + bold( desc );
                        }
                    },
        JVMS( "https://docs.oracle.com/javase/specs/jvms/" )
                    {
                    // typical http://docs.oracle.com/javase/specs/jvms/se7/html/jvms-4.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        Acronym acronym = new Acronym();
                        acronym.setFileBeingProcessedAndFileBeingDistributed( fileBeingProcessed,
                                fileBeingDistributed );
                        return ORACLES + acronym.expandNoRef( "JVMS" ) + ": " + bold( desc );
                        }
                    },
        MIDP( "https://docs.oracle.com/javame/config/cldc/" )
                    {
                    // typical http://docs.oracle.com/javame/config/cldc/ref-impl/midp2
                    // .0/jsr118/javax/microedition/lcdui/choice.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return "MIDP Javadoc on " + bold( desc );
                        }
                    },
        PLATFORM( JDKandJREVersions.ORACLE_JAVA_SE + "docs/platform/" )
                    {
                    // typical http://docs.oracle.com/javase/" + JDKandJREVersions.oracle + "/docs/platform/serialization/spec/protocol.html
                    // must come near end, since there are finer possibilities. This is a catch all.

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildDualLink( ref, elaborate( ref, desc ), notes );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "JDK Platform Guide to " + bold( desc );
                        }
                    },
        PRODUCTS( "http://www.oracle.com/us/products" )
                    {
                    // typical  http://java.sun.com/products/jsp/tutorial/TagLibrariesTOC.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Product Info on " + bold( desc );
                        }
                    },
        TECHNETWORK( "http://www.oracle.com/technetwork/" )
                    {
                    // typical http://www.oracle.com/technetwork/java/download-139443.html}

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        // was http://java.sun.com/products/archive/
                        // now http://www.oracle.com/technetwork/java/archive-139210.html
                        return ORACLES + "Technetwork " + bold( desc );
                        }
                    },
        TECHNOTE_GUIDE( JDKandJREVersions.ORACLE_JAVA_SE + "docs/technotes/guides/" )
                    {
                    // typical http://docs.oracle
                    // .com/javase/" + JDKandJREVersions.oracle + "/docs/technotes/guides/deployment/deployment-guide/pack200.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildDualLink( ref, elaborate( ref, desc ), notes );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Technote Guide on " + bold( desc );
                        }
                    },
        TOOLS( JDKandJREVersions.ORACLE_JAVA_SE + "docs/technotes/tools/" )
                    {
                    // typical http://docs.oracle.com/javase/" + JDKandJREVersions.oracle + "/docs/technotes/tools/windows/javadoc.html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @param notes additional notes
                     * @return html to link to site, and possibly local as well.
                     */
                    @Override
                    String expand( final String ref, final String desc, final String notes )
                        {
                        return buildDualLink( ref, elaborate( ref, desc ), notes );
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        if ( desc.endsWith( ".exe" ) )
                            {
                            return ORACLES + "JDK Tool Guide to <span class=\"exe\">"
                                   + desc
                                   + "</span>";
                            }
                        else
                            {
                            return ORACLES + "JDK Tool Guide to " + bold( desc );
                            }
                        }
                    },
        TUTORIAL( JDKandJREVersions.ORACLE_JAVA_SE + "tutorial/" )
                    {
                    // typical  http://docs.oracle.com/javase/tutorial/uiswing/concurrency/

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "tutorial on " + bold( desc );
                        }
                    },
        WEBSTART( JDKandJREVersions.ORACLE_JAVA_SE + "docs/guide/javaws/" )
                    {
                    // typical. http://docs.oracle.com/javase/1.5.0/docs/guide/javaws/developersguide/cdinstall.03.06
                    // .html

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Java Web Start Guide on " + bold( desc );
                        }
                    },
        GENERAL_SE( JDKandJREVersions.ORACLE_JAVA_SE + "docs/" )
                    {
                    // typical http://docs.oracle.com/javase/" + JDKandJREVersions.oracle + "/docs/jre/api/plugin/dom/index.html
                    // must come near end, since there are finer possibilities. This is a catch all.
                    // might not be local

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Java documentation on " + bold( desc );
                        }
                    },
        JCP( "http://jcp.org" )
                    {
                    /**
                     * guts to Generate reference to a Java Community Process HTML document.
                     * @param ref  usually a fully qualified referenced jcp site,
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return "Java Community Process documentation on " + bold( desc );
                        }
                    },
        GENERAL( "" )
                    {
                    // typical. http://docs.oracle.com/javase/1.5.0/docs/guide/javaws/developersguide/cdinstall.03.06
                    // .html

                    /**
                     * Does the reference match the dna pattern of this possibility
                     * @param ref reference, usually a fq url.
                     */
                    @Override
                    boolean isDnaMatch( String ref )
                        {
                        return true; /* match anything */
                        }

                    /**
                     * guts to Generate reference to a oracle HTML document.
                     * @param ref  usually a fully qualified referenced to sun or oracle site,
                     *             and also a pi/java/awt/package-summary.html
                     * @param desc human description of what it is.
                     * @return html expanded description with html decoration.
                     */
                    @Override
                    String elaborate( final String ref, final String desc )
                        {
                        return ORACLES + "Miscellaneous documentation on " + bold( desc );
                        }
                    };

    /**
     * file where generated code will eventually be inserted
     */
    private static File fileBeingDistributed;

    /**
     * file where macros are
     */
    private static File fileBeingProcessed;

    /**
     * lead string that marks this pattern
     */
    private final String dna;

    /**
     * Constructor
     *
     * @param dna lead chars that indicate this possibility
     */
    Possibility( String dna )
        {
        this.dna = dna;
        }

    /**
     * get bold version of description.
     *
     * @param desc description of this link.
     *
     * @return bold version of description.
     */
    private static String bold( String desc )
        {
        return "<strong>" + desc + "</strong>";
        }

    /**
     * Build HTML to for broken links to oracle remote and local.
     *
     * @param elaborateDesc expanded human-readable description  for the link.
     * @param notes         additional notes
     *
     * @return generated HTML
     */
    static String buildBrokenLink( final String elaborateDesc, final String notes )
        {
        final String description;
        if ( notes.length() > 0 )
            {
            description = elaborateDesc + ":" + notes;
            }
        else
            {
            description = elaborateDesc;
            }
        return "<div class=\"oracle\">" + Tools.completeLink( "jgloss/oracle.html", description,
                "broken", fileBeingDistributed ) + "</div>\n";
        }

    /**
     * Build HTML to for links to oracle remote and local.
     *
     * @param refWithSlashes reference with / instead of File.separatorChar. partial or complete url.
     * @param elaborateDesc  expanded human-readable description  for the link.
     * @param notes          additional notes
     *
     * @return generated HTML
     */
    static String buildDualLink( String refWithSlashes, final String elaborateDesc, final String notes )
        {
        refWithSlashes = Misc.miniURLEncode( refWithSlashes );
        final FastCat sb = new FastCat( 17 );
        sb.append( "<div class=\"oracle\">" );
        sb.append( elaborateDesc );
        if ( notes.length() > 0 )
            {
            sb.append( " : " );
            sb.append( notes );
            }
        sb.append( " : available:<ul><li>" );
        sb.append( buildWebLinkToJDK( refWithSlashes ) );
        sb.append( "</li><li>" );
        sb.append( buildLocalLinkToCurrentJDK( refWithSlashes ) );
        sb.append( " " );
        sb.append( buildJDriveDescription() );
        sb.append( "</li>" );
        if ( SHOW_OLD_JAVA )
            {
            sb.append( "<li>" );
            sb.append( buildLocalLinkToOldJDK( refWithSlashes ) );
            sb.append( " " );
            sb.append( buildJDriveDescription() );
            sb.append( "</li>" );
            }
        sb.append( "</ul></div>" );
        return sb.toString();
        }// /method

    /**
     * Build HTML to describe the J: drive links.
     *
     * @return generated HTML
     */
    private static String buildJDriveDescription()
        {
        final FastCat sb = new FastCat( 3 );
        sb.append( "on your local Windows <a class=\"plain\" href=\"" );
        sb.append( Tools.relativeURL( "jgloss/jdrive.html", fileBeingDistributed ) );
        sb.append( "\"><span class=\"drive\">J:</span> drive</a>." );
        return sb.toString();
        }

    /**
     * /
     * Build HTML for link to JavaDoc in the current JDK.
     *
     * @param localRefWithSlashes reference with / instead of File.separatorChar . partial or complete url.
     *
     * @return generated HTML
     */
    private static String buildLocalLinkToCurrentJDK( String localRefWithSlashes )
        {
        localRefWithSlashes = ST.chopLeadingString( localRefWithSlashes, JDKandJREVersions.ORACLE_JAVA_SE );
        final FastCat sb = new FastCat( 8 );
        sb.append( "in the current <a class=\"jdrive\" href=\"" );
        sb.append( JDK_URL );
        sb.append( "/" );
        sb.append( localRefWithSlashes );
        sb.append( "\">" );
        sb.append( "JDK <span class=\"version\">" );
        sb.append( RECOMMENDED_JDK_FULL_VERSION );
        sb.append( "</span></a> " );
        return sb.toString();
        }

    /**
     * /**
     * Build HTML for link to JavaDoc in the current JDK.
     *
     * @param localRefWithSlashes reference with / instead of File.separatorChar . partial or complete url.
     *
     * @return generated HTML
     */
    private static String buildLocalLinkToOldJDK( String localRefWithSlashes )
        {
        localRefWithSlashes = ST.chopLeadingString( localRefWithSlashes, JDKandJREVersions.ORACLE_JAVA_SE );
        final FastCat sb = new FastCat( 8 );
        sb.append( "in the previous <a class=\"jdrive\" href=\"" );
        sb.append( OLD_JDK_URL );
        sb.append( "/" );
        sb.append( localRefWithSlashes );
        sb.append( "\">" );
        sb.append( "JDK <span class=\"version\">" );
        sb.append( OLD_JDK_FULL_VERSION );
        sb.append( "</span></a> " );
        return sb.toString();
        }

    /**
     * generate HTML for simple link to one target
     *
     * @param ref            fq url
     * @param elaboratedDesc description with html decoration
     * @param notes          additional notes
     *
     * @return generated HTML to link
     */
    private static String buildSimpleLink( final String ref, final String elaboratedDesc, final String notes )
        {
        final String cssClass = Global.assignCSSClasses.assignCSSClass( ref, fileBeingDistributed );
        final FastCat sb = new FastCat( 12 );
        sb.append( "<div class=\"oracle\"><a " );
        if ( cssClass != null )
            {
            sb.append( "class=\"" );
            sb.append( cssClass );
            sb.append( "\" " );
            }
        sb.append( "href=\"" );
        sb.append( ref );
        sb.append( "\">" );
        sb.append( elaboratedDesc );
        sb.append( "</a>" );
        if ( notes.length() > 0 )
            {
            sb.append( " : " );
            sb.append( notes );
            }
        sb.append( "</div>\n" );
        return sb.toString();
        }

    /**
     * Build HTML for link to JavaDoc at Oracle
     *
     * @param refWithSlashes reference with / instead of File.separatorChar. partial or complete url.
     *
     * @return generated HTML
     */
    private static String buildWebLinkToJDK( String refWithSlashes )
        {
        // e.g. http://docs.oracle.com/javase/" + JDKandJREVersions.ORACLE_JAVA_SE_JAVA_SE + "/docs/technotes/guides/net/proxies.html
        final FastCat sb = new FastCat( 3 );
        sb.append( "on the web at <a class=\"oracle\" href=\"" );
        sb.append( refWithSlashes );
        sb.append( "\">Oracle.com</a>" );
        return sb.toString();
        }

    /**
     * Static setter to configure which file generated macro expansion will be inserted.
     *
     * @param fileBeingProcessed   file where macros to expand are.
     * @param fileBeingDistributed file where expanded macros will be written
     */
    static void setFileBeingProcessedAndFileBeingDistributed( File fileBeingProcessed, File fileBeingDistributed )
        {
        Possibility.fileBeingProcessed = fileBeingProcessed;
        Possibility.fileBeingDistributed = fileBeingDistributed;
        }

    /**
     * guts to Generate reference to a oracle HTML document.
     *
     * @param ref  usually a fully qualified referenced to sun or oracle site,
     *             and also a pi/java/awt/package-summary.html
     * @param desc human description of what it is.
     *
     * @return html expanded description with html decoration.
     */
    String elaborate( final String ref, final String desc )
        {
        return desc;
        }

    /**
     * default guts to Generate reference to a oracle HTML document.
     *
     * @param ref   usually a fully qualified referenced to sun or oracle site,
     *              and also a pi/java/awt/package-summary.html
     * @param desc  human description of what it is.
     * @param notes additional notes
     *
     * @return html to link to site, and possibly local as well.
     */
    String expand( final String ref, final String desc, final String notes )
        {
        return buildSimpleLink( ref, elaborate( ref, desc ), notes );
        }

    /**
     * Does the reference match the dna pattern of this possibility
     *
     * @param ref reference, usually a fq url.
     *
     * @return true if this  matches this pattern
     */
    boolean isDnaMatch( String ref )
        {
        return ref.startsWith( dna );
        }
    }