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