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}