001package Torello.HTML;
002
003import java.util.HashMap;
004
005/**
006 * An enumeration of the standard Search Engine index-directives.
007 * 
008 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=ROBOTS>
009 *
010 * @see Features.Meta#insertRobots(Vector, boolean, boolean)
011 * @see Features.Meta#getAllRobots(Vector)
012 * @see Features.Meta#robotsMetaTag
013 */
014public enum Robots
015{
016    /**
017     * Tells a search engine to index a page. Note that you don’t need to add this meta tag; it’s
018     * the default.
019     */
020    Index("Index"),
021
022    /** Tells a search engine not to index a page.*/
023    NoIndex("NoIndex"),
024
025    /**
026     * Even if the page isn’t indexed, the crawler should follow all the links on a page and pass
027     * equity to the linked pages.
028     */
029    Follow("Follow"),
030
031    /** Tells a crawler not to follow any links on a page or pass along any link equity. */
032    NoFollow("NoFollow"),
033
034    /** Tells a crawler not to index any images on a page. */
035    NoImageIndex("NoImageIndex"),
036
037    /**
038     * Equivalent to using both the {@code 'noindex'} and {@code 'nofollow'} tags
039     * simultaneously.
040     */
041    None("None"),
042
043    /** Search engines should not show a cached link to this page on a SERP. */
044    NoArchive("NoArchive"),
045
046    /** Same as {@code 'noarchive'}, but only used by Internet Explorer and Firefox. */
047    NoCache("NoCache"),
048
049    /**
050     * Tells a search engine not to show a snippet of this page (i.e. meta {@code 'description'})
051     * of this page on a SERP.
052     */
053    NoSnippet("NoSnippet"),
054
055    /** Prevents all search-engine stuff. */
056    All("All"),
057
058    /**
059     * [OBSOLETE]: Prevents search engines from using a page’s DMOZ description as the SERP snippet
060     * for this page. However, DMOZ was retired in early 2017, making this tag obsolete.
061     */
062    NoYDir("NoYDir"),
063
064    /**
065     * [OBSOLETE]: Prevents search engines from using a page’s DMOZ description as the SERP snippet
066     * for this page. However, DMOZ was retired in early 2017, making this tag obsolete.
067     */
068    NoODP("NoODP");
069
070    public final String name;
071
072    // The constructor
073    private Robots(String name) { this.name = name; }
074
075    // a robots lookup table.... Populate the lookup table on loading time
076    private static final HashMap<String, Robots> lookup = new HashMap<>();
077
078    // static initializer for the above hashmap
079    static { for (Robots r : Robots.values()) lookup.put(r.name.toLowerCase(), r); }
080
081    /**
082     * This will retrieve the robot that maps to this parameter-{@code String}.  The {@code String}
083     * should be a valid HMTL Meta-Tag {@code 'robots'} attribute-<B STYLE="color:red;">value</B>.
084     * The valid values are the ones listed by this enumeration.  If an attempt is made to retrieve
085     * a copy of an invalid {@code 'robots'} attribute-<B STYLE="color:red;">value</B>, then a 
086     * {@code MalformedHTMLException} will be thrown.
087     *
088     * @param robotParam This parameter should be a {@code String} retrieved from a vectorized-html
089     * page that is was found inside the {@code content='...'}
090     * attribute-<B STYLE="color:red;">value</B> of a {@code 'robots'} meta-tag.
091     *
092     * @return An instance of this enumerated type.  The instance will map to the
093     * passed-{@code String} parameter.
094     *
095     * @throws MalformedHTMLException If the passed parameter was not a valid robotParam.
096     *
097     * @see Features.Meta#insertRobots(Vector, boolean, boolean)
098     * @see Features.Meta#getAllRobots(Vector)
099     */
100    public static Robots getRobot(String robotParam) throws MalformedHTMLException
101    {
102        Robots r = lookup.get(robotParam.toLowerCase());
103
104        if (r != null) return r;
105
106        else
107
108            throw new MalformedHTMLException(
109                "The robot parameter you are asking about does not exist: [" + robotParam + "]. " +
110                "Please review the list of valid parameters to meta-tag robots."
111            );
112    }
113
114    /**
115     * This will retrieve the robot that maps to this parameter string.  The string should be a
116     * valid HMTL Meta-Tag robots attribute value.  The valid values are the ones listed by this
117     * enumeration.
118     *
119     * <BR /><BR /><B>NOTE:</B> This method will not throw an "Invalid HTML Exception" if an
120     * invalid robots-parameter is passed.  Instead {@code 'null'} will simply be returned.
121     *
122     * @param robotParam This parameter should be a string retrieved from a vectorized-html page
123     * that was in the {@code content='...'} attribute-field of a robots meta-tag.
124     * 
125     * @return An instance of this enumerated type.  The instance will be retrieved using
126     * {@code 'robotParam'}.
127     *
128     *  @see Features.Meta#insertRobots(Vector, boolean, boolean)
129     * @see Features.Meta#getAllRobots(Vector)
130     */
131    public static Robots getRobotNOMHE(String robotParam)
132    { return lookup.get(robotParam.toLowerCase()); }
133}