0
# Dependency Resolution (Deprecated)
1

2
The kotlin-script-util library provides deprecated dependency resolution infrastructure for Kotlin scripts using annotation-based declarations. This system allows scripts to declare dependencies and repositories using file-level annotations that are processed at script compilation time.
3

4
**Note:** All dependency resolution classes and annotations in this module are deprecated. Use the new annotation and processing code from the `kotlin-scripting-dependencies` library for new implementations.
5

6
## Dependency Annotations
7

8
### DependsOn
9

10
Annotation for declaring script dependencies using Maven coordinates or file paths.
11

12
```kotlin { .api }
13
@Deprecated("Use annotations an processing code from the kotlin-scripting-dependencies library")
14
@Target(AnnotationTarget.FILE)
15
@Repeatable
16
@Retention(AnnotationRetention.SOURCE)
17
annotation class DependsOn(
18
    val value: String = "",
19
    val groupId: String = "",
20
    val artifactId: String = "",
21
    val version: String = ""
22
)
23
```
24

25
**Parameters:**
26
- `value: String` - Complete dependency string or file path
27
- `groupId: String` - Maven group ID (alternative to value)
28
- `artifactId: String` - Maven artifact ID (alternative to value) 
29
- `version: String` - Maven version (alternative to value)
30

31
**Usage Examples:**
32

33
```kotlin
34
// Using complete Maven coordinates
35
@file:DependsOn("org.apache.commons:commons-lang3:3.12.0")
36

37
// Using separate coordinate components
38
@file:DependsOn(groupId = "org.apache.commons", artifactId = "commons-lang3", version = "3.12.0")
39

40
// Using local file path
41
@file:DependsOn("./lib/my-library.jar")
42

43
// Multiple dependencies
44
@file:DependsOn("com.google.guava:guava:31.1-jre")
45
@file:DependsOn("org.slf4j:slf4j-api:1.7.36")
46

47
import org.apache.commons.lang3.StringUtils
48
import com.google.common.collect.Lists
49

50
println(StringUtils.capitalize("hello world"))
51
val list = Lists.newArrayList("a", "b", "c")
52
```
53

54
### Repository
55

56
Annotation for declaring additional Maven repositories for dependency resolution.
57

58
```kotlin { .api }
59
@Deprecated("Use annotations an processing code from the kotlin-scripting-dependencies library")
60
@Target(AnnotationTarget.FILE)
61
@Repeatable
62
@Retention(AnnotationRetention.SOURCE)
63
annotation class Repository(
64
    val value: String = "",
65
    val id: String = "",
66
    val url: String = ""
67
)
68
```
69

70
**Parameters:**
71
- `value: String` - Repository URL or local directory path
72
- `id: String` - Repository identifier (optional)
73
- `url: String` - Repository URL (alternative to value)
74

75
**Usage Examples:**
76

77
```kotlin
78
// Using Maven Central alternative
79
@file:Repository("https://repo1.maven.org/maven2/")
80

81
// Using repository with ID
82
@file:Repository(id = "spring-releases", url = "https://repo.spring.io/release/")
83

84
// Using local directory repository
85
@file:Repository("./local-repo")
86

87
// Using JCenter
88
@file:Repository("https://jcenter.bintray.com/")
89

90
@file:DependsOn("org.springframework:spring-core:5.3.21")
91

92
import org.springframework.util.StringUtils
93
```
94

95
### Import (Deprecated)
96

97
Annotation for declaring script imports.
98

99
```kotlin { .api }
100
@Deprecated("Use your own annotations, this will be removed soon")
101
@Target(AnnotationTarget.FILE)
102
@Repeatable
103
@Retention(AnnotationRetention.SOURCE)
104
annotation class Import(vararg val paths: String)
105
```
106

107
**Usage Example:**
108

109
```kotlin
110
@file:Import("./utils/helpers.kts", "./config/settings.kts")
111

112
// Script content can now use declarations from imported scripts
113
```
114

115
### CompilerOptions (Deprecated)
116

117
Annotation for specifying compiler options for script compilation.
118

119
```kotlin { .api }
120
@Deprecated("Use your own annotations, this will be removed soon")
121
@Target(AnnotationTarget.FILE)
122
@Repeatable
123
@Retention(AnnotationRetention.SOURCE)
124
annotation class CompilerOptions(vararg val options: String)
125
```
126

127
**Usage Example:**
128

129
```kotlin
130
@file:CompilerOptions("-Xjsr305=strict", "-Xjvm-default=all")
131

132
// Script compiled with specified compiler options
133
```
134

135
## Dependency Resolvers
136

137
### KotlinAnnotatedScriptDependenciesResolver
138

139
Main resolver that processes dependency annotations and resolves them using pluggable resolver implementations.
140

141
```kotlin { .api }
142
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies and kotlin-scripting-dependencies-maven")
143
open class KotlinAnnotatedScriptDependenciesResolver(
144
    val baseClassPath: List<File>, 
145
    resolvers: Iterable<Resolver>
146
) : ScriptDependenciesResolver {
147
    
148
    @AcceptedAnnotations(DependsOn::class, Repository::class)
149
    fun resolve(
150
        script: ScriptContents,
151
        environment: Map<String, Any?>?,
152
        report: (ScriptDependenciesResolver.ReportSeverity, String, ScriptContents.Position?) -> Unit,
153
        previousDependencies: KotlinScriptExternalDependencies?
154
    ): Future<KotlinScriptExternalDependencies?>
155
}
156
```
157

158
**Parameters:**
159
- `baseClassPath: List<File>` - Base classpath entries always included
160
- `resolvers: Iterable<Resolver>` - Pluggable resolvers for different dependency types
161

162
**Usage Example:**
163

164
```kotlin
165
import org.jetbrains.kotlin.script.util.KotlinAnnotatedScriptDependenciesResolver
166
import org.jetbrains.kotlin.script.util.resolvers.DirectResolver
167
import org.jetbrains.kotlin.script.util.resolvers.FlatLibDirectoryResolver
168

169
// Create resolver with base classpath and multiple resolver implementations
170
val baseClasspath = listOf(File("./lib/base.jar"))
171
val resolvers = listOf(
172
    DirectResolver(), // For direct file paths
173
    FlatLibDirectoryResolver(File("./lib")) // For flat library directories
174
)
175

176
val dependencyResolver = KotlinAnnotatedScriptDependenciesResolver(baseClasspath, resolvers)
177

178
// The resolver processes @DependsOn and @Repository annotations in scripts
179
```
180

181
### LocalFilesResolver
182

183
Simplified resolver for local file dependencies only.
184

185
```kotlin { .api }
186
@Deprecated("Use FileSystemDependenciesResolver from kotlin-scripting-dependencies instead")
187
class LocalFilesResolver : KotlinAnnotatedScriptDependenciesResolver(
188
    emptyList(), 
189
    arrayListOf(DirectResolver())
190
)
191
```
192

193
**Usage Example:**
194

195
```kotlin
196
import org.jetbrains.kotlin.script.util.LocalFilesResolver
197

198
// Used in script templates for local dependency resolution
199
val resolver = LocalFilesResolver()
200

201
// Automatically resolves @DependsOn annotations pointing to local files
202
// Example: @file:DependsOn("./lib/utility.jar")
203
```
204

205
## Resolver Interface
206

207
### Resolver
208

209
Base interface for dependency resolver implementations.
210

211
```kotlin { .api }
212
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
213
interface Resolver {
214
    fun tryResolve(dependsOn: DependsOn): Iterable<File>?
215
    fun tryAddRepo(annotation: Repository): Boolean
216
}
217
```
218

219
**Methods:**
220
- `tryResolve`: Attempts to resolve a DependsOn annotation to file paths
221
- `tryAddRepo`: Attempts to add a repository from a Repository annotation
222

223
## Basic Resolver Implementations
224

225
### GenericRepositoryWithBridge
226

227
Bridge interface that combines GenericResolver and legacy Resolver interfaces.
228

229
```kotlin { .api }
230
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
231
interface GenericRepositoryWithBridge : GenericResolver, Resolver {
232
    // Inherits from GenericResolver:
233
    // fun tryResolve(artifactCoordinates: GenericArtifactCoordinates): Iterable<File>?
234
    // fun tryAddRepository(repositoryCoordinates: GenericRepositoryCoordinates): Boolean
235
    
236
    // Inherits from Resolver:
237
    // fun tryResolve(dependsOn: DependsOn): Iterable<File>?
238
    // fun tryAddRepo(annotation: Repository): Boolean
239
}
240
```
241

242
### DirectResolver
243

244
Resolves dependencies that are direct file or directory paths.
245

246
```kotlin { .api }
247
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
248
class DirectResolver : GenericRepositoryWithBridge {
249
    // GenericResolver implementation
250
    fun tryResolve(artifactCoordinates: GenericArtifactCoordinates): Iterable<File>?
251
    fun tryAddRepository(repositoryCoordinates: GenericRepositoryCoordinates): Boolean
252
    
253
    // Resolver implementation
254
    fun tryResolve(dependsOn: DependsOn): Iterable<File>?
255
    fun tryAddRepo(annotation: Repository): Boolean
256
}
257
```
258

259
**Usage Example:**
260

261
```kotlin
262
import org.jetbrains.kotlin.script.util.resolvers.DirectResolver
263

264
val resolver = DirectResolver()
265

266
// Can resolve direct file paths in @DependsOn annotations
267
// Example: @file:DependsOn("./lib/my-library.jar")
268
// Example: @file:DependsOn("/absolute/path/to/library.jar")
269
```
270

271
### FlatLibDirectoryResolver
272

273
Resolves dependencies by searching in flat library directories.
274

275
```kotlin { .api }
276
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
277
class FlatLibDirectoryResolver(vararg paths: File) : GenericRepositoryWithBridge {
278
    fun tryResolve(artifactCoordinates: GenericArtifactCoordinates): Iterable<File>?
279
    fun tryAddRepository(repositoryCoordinates: GenericRepositoryCoordinates): Boolean
280
    
281
    companion object {
282
        fun tryCreate(annotation: Repository): FlatLibDirectoryResolver?
283
        fun tryCreate(repositoryCoordinates: GenericRepositoryCoordinates): FlatLibDirectoryResolver?
284
    }
285
}
286
```
287

288
**Parameters:**
289
- `paths: File` - Directory paths to search for dependencies
290

291
**Usage Example:**
292

293
```kotlin
294
import org.jetbrains.kotlin.script.util.resolvers.FlatLibDirectoryResolver
295

296
// Create resolver for specific library directories
297
val resolver = FlatLibDirectoryResolver(
298
    File("./lib"),
299
    File("./third-party"),
300
    File("/usr/local/lib")
301
)
302

303
// Can resolve dependencies by filename in the specified directories
304
// Example: @file:DependsOn("commons-lang3-3.12.0.jar")
305
```
306

307
## Generic Resolver Interfaces
308

309
### GenericArtifactCoordinates
310

311
Interface representing artifact coordinates for dependency resolution.
312

313
```kotlin { .api }
314
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
315
interface GenericArtifactCoordinates {
316
    val string: String
317
}
318
```
319

320
### GenericRepositoryCoordinates
321

322
Interface representing repository coordinates.
323

324
```kotlin { .api }
325
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
326
interface GenericRepositoryCoordinates {
327
    val string: String
328
    val name: String?
329
    val url: URL?
330
    val file: File?
331
}
332
```
333

334
### BasicArtifactCoordinates
335

336
Basic implementation of artifact coordinates using string representation.
337

338
```kotlin { .api }
339
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
340
open class BasicArtifactCoordinates(
341
    override val string: String
342
) : GenericArtifactCoordinates
343
```
344

345
### BasicRepositoryCoordinates
346

347
Basic implementation of repository coordinates.
348

349
```kotlin { .api }
350
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
351
open class BasicRepositoryCoordinates(
352
    override val string: String,
353
    override val name: String?
354
) : GenericRepositoryCoordinates {
355
    override val url: URL? = null
356
    override val file: File? = null
357
}
358
```
359

360
### MavenArtifactCoordinates
361

362
Implementation for Maven-style artifact coordinates.
363

364
```kotlin { .api }
365
@Deprecated("Use new resolving classes from kotlin-scripting-dependencies")
366
open class MavenArtifactCoordinates(
367
    val value: String?,
368
    val groupId: String?,
369
    val artifactId: String?,
370
    val version: String?
371
) : GenericArtifactCoordinates {
372
    override val string: String // Computed Maven coordinate string
373
}
374
```
375

376
## Complete Usage Example
377

378
```kotlin
379
// Script file example using dependency resolution annotations
380

381
@file:Repository("https://repo1.maven.org/maven2/")
382
@file:Repository("./local-lib")
383
@file:DependsOn("org.apache.commons:commons-lang3:3.12.0")
384
@file:DependsOn("./local-lib/custom-utility.jar")
385

386
import org.apache.commons.lang3.StringUtils
387
// Import from local-lib/custom-utility.jar would also be available
388

389
fun processText(input: String): String {
390
    return StringUtils.capitalize(StringUtils.trim(input))
391
}
392

393
println(processText("  hello world  ")) // "Hello world"
394
```
395

396
## Migration Notes
397

398
When migrating to the new kotlin-scripting-dependencies library:
399

400
1. Replace deprecated annotations:
401
   ```kotlin
402
   // Old
403
   import org.jetbrains.kotlin.script.util.DependsOn
404
   
405
   // New
406
   import kotlin.script.experimental.dependencies.DependsOn
407
   ```
408

409
2. Replace resolver implementations with new equivalents from kotlin-scripting-dependencies
410

411
3. Update script template definitions to use new dependency resolution APIs
412

413
## Types
414

415
```kotlin { .api }
416
// From kotlin.script.dependencies package
417
interface ScriptDependenciesResolver {
418
    enum class ReportSeverity { FATAL, ERROR, WARNING, INFO, DEBUG }
419
    
420
    fun resolve(
421
        script: ScriptContents,
422
        environment: Map<String, Any?>?,
423
        report: (ReportSeverity, String, ScriptContents.Position?) -> Unit,
424
        previousDependencies: KotlinScriptExternalDependencies?
425
    ): Future<KotlinScriptExternalDependencies?>
426
}
427

428
interface KotlinScriptExternalDependencies {
429
    val classpath: Iterable<File>
430
    val imports: Iterable<String>
431
    val sources: Iterable<File>
432
}
433

434
interface ScriptContents {
435
    val annotations: Iterable<Annotation>
436
    val file: File?
437
    val text: CharSequence?
438
    
439
    data class Position(val line: Int, val col: Int)
440
}
441
```