001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.maven.tools.plugin.extractor.annotations.converter;
020
021import java.net.URI;
022import java.util.Optional;
023
024import org.apache.maven.tools.plugin.extractor.annotations.converter.tag.block.JavadocBlockTagToHtmlConverter;
025import org.apache.maven.tools.plugin.javadoc.FullyQualifiedJavadocReference;
026import org.apache.maven.tools.plugin.javadoc.JavadocReference;
027
028/**
029 * Context which is passed to {@link JavadocBlockTagsToXhtmlConverter}, {@link JavadocInlineTagsToXhtmlConverter},
030 * {@link JavadocBlockTagToHtmlConverter} and {@link JavadocBlockTagToHtmlConverter}.
031 * It contains metadata about the container class and allows to resolve class or member names
032 * which are not fully qualified as well as creating (deep-) links to javadoc pages.
033 */
034public interface ConverterContext {
035    /**
036     *
037     * @return the module name of the container class
038     */
039    Optional<String> getModuleName();
040
041    /**
042     *
043     * @return the package name of the container class
044     */
045    String getPackageName();
046
047    /**
048     *
049     * @param reference
050     * @return true in case either the current container class or any of its super classes are referenced
051     */
052    boolean isReferencedBy(FullyQualifiedJavadocReference reference);
053
054    /**
055     *
056     * @return a location text (human readable) indicating where in the container class the conversion is triggered
057     * (should be as specific as possible to ease debugging)
058     */
059    String getLocation();
060
061    /**
062     * Resolves a given javadoc reference, according to the rules of
063     * <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#JSWOR655">
064     * Javadoc's search order</a>.
065     * @param reference the reference to resolve
066     * @return the resolved fully qualified reference
067     * @throws IllegalArgumentException in case the reference cannot be resolved
068     */
069    FullyQualifiedJavadocReference resolveReference(JavadocReference reference);
070
071    /**
072     *
073     * @return {@code true} if links to javadoc pages could potentially be generated with
074     * {@link #getUrl(FullyQualifiedJavadocReference)}.
075     */
076    boolean canGetUrl();
077
078    /**
079     * Returns a (deep-)link to the javadoc page for the given reference
080     * @param reference the reference for which to get the url
081     * @return the link
082     * @throws IllegalArgumentException in case no javadoc link could be generated for the given reference
083     * @throws IllegalStateException in case no javadoc source sites have been configured
084     * (i.e. {@link #canGetUrl()} returns {@code false})
085     */
086    URI getUrl(FullyQualifiedJavadocReference reference);
087
088    /**
089     * Returns the value of a referenced static field.
090     * @param reference the code reference towards a static field
091     * @return the value of the static field given by the {@code reference}
092     * @throws IllegalArgumentException in case the reference does not point to a valid static field
093     */
094    String getStaticFieldValue(FullyQualifiedJavadocReference reference);
095
096    /**
097     * Returns the base url to use for internal javadoc links
098     * @return the base url for internal javadoc links (may be {@code null}).
099     */
100    URI getInternalJavadocSiteBaseUrl();
101
102    /**
103     * Stores some attribute in the current context
104     * @param <T>
105     * @param name
106     * @param value
107     * @return the old attribute value or null.
108     */
109    <T> T setAttribute(String name, T value);
110
111    /**
112     * Retrieves some attribute value from the current context.
113     * @param <T>
114     * @param name
115     * @param clazz
116     * @param defaultValue
117     * @return the value of the attribute with the given name or {@code null} if it does not exist
118     */
119    <T> T getAttribute(String name, Class<T> clazz, T defaultValue);
120}