1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
package org.jetbrains.dokka
import com.google.inject.Inject
import com.google.inject.Singleton
import com.intellij.psi.PsiMethod
import com.intellij.util.io.*
import org.jetbrains.kotlin.descriptors.*
import org.jetbrains.kotlin.load.java.descriptors.JavaCallableMemberDescriptor
import org.jetbrains.kotlin.load.java.descriptors.JavaClassDescriptor
import org.jetbrains.kotlin.load.java.descriptors.JavaMethodDescriptor
import org.jetbrains.kotlin.load.java.descriptors.JavaPropertyDescriptor
import org.jetbrains.kotlin.name.FqName
import org.jetbrains.kotlin.resolve.DescriptorUtils
import org.jetbrains.kotlin.resolve.descriptorUtil.fqNameSafe
import org.jetbrains.kotlin.resolve.descriptorUtil.parents
import java.io.ByteArrayOutputStream
import java.io.PrintWriter
import java.net.HttpURLConnection
import java.net.URL
import java.net.URLConnection
import java.nio.file.Path
import java.security.MessageDigest
fun ByteArray.toHexString() = this.joinToString(separator = "") { "%02x".format(it) }
@Singleton
class ExternalDocumentationLinkResolver @Inject constructor(
val options: DocumentationOptions,
val logger: DokkaLogger
) {
val packageFqNameToLocation = mutableMapOf<FqName, ExternalDocumentationRoot>()
val formats = mutableMapOf<String, InboundExternalLinkResolutionService>()
class ExternalDocumentationRoot(val rootUrl: URL, val resolver: InboundExternalLinkResolutionService, val locations: Map<String, String>) {
override fun toString(): String = rootUrl.toString()
}
val cacheDir: Path? = options.cacheRoot?.resolve("packageListCache")?.apply { createDirectories() }
val cachedProtocols = setOf("http", "https", "ftp")
fun URL.doOpenConnectionToReadContent(timeout: Int = 10000, redirectsAllowed: Int = 16): URLConnection {
val connection = this.openConnection()
connection.connectTimeout = timeout
when (connection) {
is HttpURLConnection -> {
return when (connection.responseCode) {
in 200..299 -> {
connection
}
HttpURLConnection.HTTP_MOVED_PERM,
HttpURLConnection.HTTP_MOVED_TEMP,
HttpURLConnection.HTTP_SEE_OTHER -> {
if (redirectsAllowed > 0) {
val newUrl = connection.getHeaderField("Location")
URL(newUrl).doOpenConnectionToReadContent(timeout, redirectsAllowed - 1)
} else {
throw RuntimeException("Too many redirects")
}
}
else -> {
throw RuntimeException("Unhandled http code: ${connection.responseCode}")
}
}
}
else -> return connection
}
}
fun loadPackageList(link: DokkaConfiguration.ExternalDocumentationLink) {
val packageListUrl = link.packageListUrl
val needsCache = packageListUrl.protocol in cachedProtocols
val packageListStream = if (cacheDir != null && needsCache) {
val packageListLink = packageListUrl.toExternalForm()
val digest = MessageDigest.getInstance("SHA-256")
val hash = digest.digest(packageListLink.toByteArray(Charsets.UTF_8)).toHexString()
val cacheEntry = cacheDir.resolve(hash)
if (cacheEntry.exists()) {
try {
val connection = packageListUrl.doOpenConnectionToReadContent()
val originModifiedDate = connection.date
val cacheDate = cacheEntry.lastModified().toMillis()
if (originModifiedDate > cacheDate || originModifiedDate == 0L) {
if (originModifiedDate == 0L)
logger.warn("No date header for $packageListUrl, downloading anyway")
else
logger.info("Renewing package-list from $packageListUrl")
connection.getInputStream().copyTo(cacheEntry.outputStream())
}
} catch (e: Exception) {
logger.error("Failed to update package-list cache for $link")
val baos = ByteArrayOutputStream()
PrintWriter(baos).use {
e.printStackTrace(it)
}
baos.flush()
logger.error(baos.toString())
}
} else {
logger.info("Downloading package-list from $packageListUrl")
packageListUrl.openStream().copyTo(cacheEntry.outputStream())
}
cacheEntry.inputStream()
} else {
packageListUrl.doOpenConnectionToReadContent().getInputStream()
}
val (params, packages) =
packageListStream
.bufferedReader()
.useLines { lines -> lines.partition { it.startsWith(DOKKA_PARAM_PREFIX) } }
val paramsMap = params.asSequence()
.map { it.removePrefix(DOKKA_PARAM_PREFIX).split(":", limit = 2) }
.groupBy({ (key, _) -> key }, { (_, value) -> value })
val format = paramsMap["format"]?.singleOrNull() ?: "javadoc"
val locations = paramsMap["location"].orEmpty()
.map { it.split("\u001f", limit = 2) }
.map { (key, value) -> key to value }
.toMap()
val resolver = if (format == "javadoc") {
InboundExternalLinkResolutionService.Javadoc()
} else {
val linkExtension = paramsMap["linkExtension"]?.singleOrNull() ?:
throw RuntimeException("Failed to parse package list from $packageListUrl")
InboundExternalLinkResolutionService.Dokka(linkExtension)
}
val rootInfo = ExternalDocumentationRoot(link.url, resolver, locations)
packages.map { FqName(it) }.forEach { packageFqNameToLocation[it] = rootInfo }
}
init {
options.externalDocumentationLinks.forEach {
try {
loadPackageList(it)
} catch (e: Exception) {
throw RuntimeException("Exception while loading package-list from $it", e)
}
}
}
fun buildExternalDocumentationLink(symbol: DeclarationDescriptor): String? {
val packageFqName: FqName =
when (symbol) {
is DeclarationDescriptorNonRoot -> symbol.parents.firstOrNull { it is PackageFragmentDescriptor }?.fqNameSafe ?: return null
is PackageFragmentDescriptor -> symbol.fqName
else -> return null
}
val externalLocation = packageFqNameToLocation[packageFqName] ?: return null
val path = externalLocation.locations[symbol.signature()] ?:
externalLocation.resolver.getPath(symbol) ?: return null
return URL(externalLocation.rootUrl, path).toExternalForm()
}
companion object {
const val DOKKA_PARAM_PREFIX = "\$dokka."
}
}
interface InboundExternalLinkResolutionService {
fun getPath(symbol: DeclarationDescriptor): String?
class Javadoc : InboundExternalLinkResolutionService {
override fun getPath(symbol: DeclarationDescriptor): String? {
if (symbol is JavaClassDescriptor) {
return DescriptorUtils.getFqName(symbol).asString().replace(".", "/") + ".html"
} else if (symbol is JavaCallableMemberDescriptor) {
val containingClass = symbol.containingDeclaration as? JavaClassDescriptor ?: return null
val containingClassLink = getPath(containingClass)
if (containingClassLink != null) {
if (symbol is JavaMethodDescriptor) {
val psi = symbol.sourcePsi() as? PsiMethod
if (psi != null) {
val params = psi.parameterList.parameters.joinToString { it.type.canonicalText }
return containingClassLink + "#" + symbol.name + "(" + params + ")"
}
} else if (symbol is JavaPropertyDescriptor) {
return "$containingClassLink#${symbol.name}"
}
}
}
// TODO Kotlin javadoc
return null
}
}
class Dokka(val extension: String) : InboundExternalLinkResolutionService {
override fun getPath(symbol: DeclarationDescriptor): String? {
val leafElement = when (symbol) {
is CallableDescriptor, is TypeAliasDescriptor -> true
else -> false
}
val path = getPathWithoutExtension(symbol)
if (leafElement) return "$path.$extension"
else return "$path/index.$extension"
}
fun getPathWithoutExtension(symbol: DeclarationDescriptor): String {
if (symbol.containingDeclaration == null)
return identifierToFilename(symbol.name.asString())
else if (symbol is PackageFragmentDescriptor) {
return symbol.fqName.asString()
} else {
return getPathWithoutExtension(symbol.containingDeclaration!!) + '/' + identifierToFilename(symbol.name.asString())
}
}
}
}
|
