1 package org.apache.maven.tools.plugin.extractor.annotations.converter;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.net.URI;
23 import java.util.Optional;
24
25 import org.apache.maven.tools.plugin.extractor.annotations.converter.tag.block.JavadocBlockTagToHtmlConverter;
26 import org.apache.maven.tools.plugin.javadoc.FullyQualifiedJavadocReference;
27 import org.apache.maven.tools.plugin.javadoc.JavadocReference;
28
29 /**
30 * Context which is passed to {@link JavadocBlockTagsToXhtmlConverter}, {@link JavadocInlineTagsToXhtmlConverter},
31 * {@link JavadocBlockTagToHtmlConverter} and {@link JavadocBlockTagToHtmlConverter}.
32 * It contains metadata about the container class and allows to resolve class or member names
33 * which are not fully qualified as well as creating (deep-) links to javadoc pages.
34 */
35 public interface ConverterContext
36 {
37 /**
38 *
39 * @return the module name of the container class
40 */
41 Optional<String> getModuleName();
42
43 /**
44 *
45 * @return the package name of the container class
46 */
47 String getPackageName();
48
49 /**
50 *
51 * @param reference
52 * @return true in case either the current container class or any of its super classes are referenced
53 */
54 boolean isReferencedBy( FullyQualifiedJavadocReference reference );
55
56 /**
57 *
58 * @return a location text (human readable) indicating where in the container class the conversion is triggered
59 * (should be as specific as possible to ease debugging)
60 */
61 String getLocation();
62
63 /**
64 * Resolves a given javadoc reference, according to the rules of
65 * <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#JSWOR655">
66 * Javadoc's search order</a>.
67 * @param reference the reference to resolve
68 * @return the resolved fully qualified reference
69 * @throws IllegalArgumentException in case the reference cannot be resolved
70 */
71 FullyQualifiedJavadocReference resolveReference( JavadocReference reference );
72
73 /**
74 *
75 * @return {@code true} if links to javadoc pages could potentially be generated with
76 * {@link #getUrl(FullyQualifiedJavadocReference)}.
77 */
78 boolean canGetUrl();
79
80 /**
81 * Returns a (deep-)link to the javadoc page for the given reference
82 * @param reference the reference for which to get the url
83 * @return the link
84 * @throws IllegalArgumentException in case no javadoc link could be generated for the given reference
85 * @throws IllegalStateException in case no javadoc source sites have been configured
86 * (i.e. {@link #canGetUrl()} returns {@code false})
87 */
88 URI getUrl( FullyQualifiedJavadocReference reference );
89
90 /**
91 * Returns the value of a referenced static field.
92 * @param reference the code reference towards a static field
93 * @return the value of the static field given by the {@code reference}
94 * @throws IllegalArgumentException in case the reference does not point to a valid static field
95 */
96 String getStaticFieldValue( FullyQualifiedJavadocReference reference );
97
98 /**
99 * 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 }