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