Skip to content

Java 어노테이션 프로세싱에서 KSP로의 참조 가이드 ​

프로그램 요소 (Program elements) ​

JavaKSP에서 가장 가까운 기능참고
AnnotationMirrorKSAnnotation
AnnotationValueKSValueArguments
ElementKSDeclaration / KSDeclarationContainer
ExecutableElementKSFunctionDeclaration
PackageElementKSFileKSP는 패키지를 프로그램 요소로 모델링하지 않음
ParameterizableKSDeclaration
QualifiedNameableKSDeclaration
TypeElementKSClassDeclaration
TypeParameterElementKSTypeParameter
VariableElementKSValueParameter / KSPropertyDeclaration

타입 (Types) ​

KSP는 명시적인 타입 해석(type resolution)이 필요하므로, Java의 일부 기능은 해석 전의 KSType 및 해당 요소들을 통해서만 수행될 수 있습니다.

JavaKSP에서 가장 가까운 기능참고
ArrayTypeKSBuiltIns.arrayType
DeclaredTypeKSType / KSClassifierReference
ErrorTypeKSType.isError
ExecutableTypeKSType / KSCallableReference
IntersectionTypeKSType / KSTypeParameter
NoTypeKSType.isErrorKSP에서 해당 없음
NullTypeKSP에서 해당 없음
PrimitiveTypeKSBuiltInsJava의 원시 타입(primitive type)과 완전히 동일하지는 않음
ReferenceTypeKSTypeReference
TypeMirrorKSType
TypeVariableKSTypeParameter
UnionType해당 없음Kotlin은 catch 블록당 하나의 타입만 가짐. UnionType은 Java 어노테이션 프로세서에서도 관찰할 수 없음
WildcardTypeKSType / KSTypeArgument

기타 (Misc) ​

JavaKSP에서 가장 가까운 기능참고
NameKSName
ElementKindClassKind / FunctionKind
ModifierModifier
NestingKindClassKind / FunctionKind
AnnotationValueVisitor
ElementVisitorKSVisitor
AnnotatedConstructKSAnnotated
TypeVisitor
TypeKindKSBuiltIns일부는 빌트인(builtins)에서 찾을 수 있으며, 그렇지 않으면 DeclaredType에 대해 KSClassDeclaration을 확인
ElementFilterCollection.filterIsInstance
ElementKindVisitorKSVisitor
ElementScannerKSTopDownVisitor
SimpleAnnotationValueVisitorKSP에서 필요하지 않음
SimpleElementVisitorKSVisitor
SimpleTypeVisitor
TypeKindVisitor
TypesResolver / utils일부 utils는 심볼 인터페이스에 통합됨
ElementsResolver / utils

세부 사항 (Details) ​

Java 어노테이션 프로세싱 API의 기능이 KSP에서 어떻게 수행되는지 확인해 보세요.

AnnotationMirror ​

JavaKSP 해당 기능
getAnnotationTypeksAnnotation.annotationType
getElementValuesksAnnotation.arguments

AnnotationValue ​

JavaKSP 해당 기능
getValueksValueArgument.value

Element ​

JavaKSP 해당 기능
asTypeksClassDeclaration.asType(...)는 KSClassDeclaration에서만 사용할 수 있습니다. 타입 인자를 제공해야 합니다.
getAnnotation구현 예정
getAnnotationMirrorsksDeclaration.annotations
getEnclosedElementsksDeclarationContainer.declarations
getEnclosingElementsksDeclaration.parentDeclaration
getKindClassKind 또는 FunctionKind에 따른 타입 확인 및 캐스팅
getModifiersksDeclaration.modifiers
getSimpleNameksDeclaration.simpleName

ExecutableElement ​

JavaKSP 해당 기능
getDefaultValue구현 예정
getParametersksFunctionDeclaration.parameters
getReceiverTypeksFunctionDeclaration.parentDeclaration
getReturnTypeksFunctionDeclaration.returnType
getSimpleNameksFunctionDeclaration.simpleName
getThrownTypesKotlin에서 필요하지 않음
getTypeParametersksFunctionDeclaration.typeParameters
isDefault부모 선언이 인터페이스인지 여부 확인
isVarArgsksFunctionDeclaration.parameters.any { it.isVarArg }

Parameterizable ​

JavaKSP 해당 기능
getTypeParametersksFunctionDeclaration.typeParameters

QualifiedNameable ​

JavaKSP 해당 기능
getQualifiedNameksDeclaration.qualifiedName

TypeElement ​

JavaKSP 해당 기능
getEnclosedElementsksClassDeclaration.declarations
getEnclosingElementksClassDeclaration.parentDeclaration
getInterfaces
kotlin
// 해석(resolution) 없이 수행할 수 있어야 함
ksClassDeclaration.superTypes
    .map { it.resolve() }
    .filter { (it?.declaration as? KSClassDeclaration)?.classKind == ClassKind.INTERFACE }
getNestingKindKSClassDeclaration.parentDeclaration 및 inner 한정자 확인
getQualifiedNameksClassDeclaration.qualifiedName
getSimpleNameksClassDeclaration.simpleName
getSuperclass
kotlin
// 해석(resolution) 없이 수행할 수 있어야 함
ksClassDeclaration.superTypes
    .map { it.resolve() }
    .filter { (it?.declaration as? KSClassDeclaration)?.classKind == ClassKind.CLASS }
getTypeParametersksClassDeclaration.typeParameters

TypeParameterElement ​

JavaKSP 해당 기능
getBoundsksTypeParameter.bounds
getEnclosingElementksTypeParameter.parentDeclaration
getGenericElementksTypeParameter.parentDeclaration

VariableElement ​

JavaKSP 해당 기능
getConstantValue구현 예정
getEnclosingElementksValueParameter.parentDeclaration
getSimpleNameksValueParameter.simpleName

ArrayType ​

JavaKSP 해당 기능
getComponentTypeksType.arguments.first()

DeclaredType ​

JavaKSP 해당 기능
asElementksType.declaration
getEnclosingTypeksType.declaration.parentDeclaration
getTypeArgumentsksType.arguments

ExecutableType ​

함수에 대한 KSType은 FunctionN<R, T1, T2, ..., TN> 계열로 표현되는 시그니처일 뿐입니다.

JavaKSP 해당 기능
getParameterTypesksType.declaration.typeParameters, ksFunctionDeclaration.parameters.map { it.type }
getReceiverTypeksFunctionDeclaration.parentDeclaration.asType(...)
getReturnTypeksType.declaration.typeParameters.last()
getThrownTypesKotlin에서 필요하지 않음
getTypeVariablesksFunctionDeclaration.typeParameters

IntersectionType ​

JavaKSP 해당 기능
getBoundsksTypeParameter.bounds

TypeMirror ​

JavaKSP 해당 기능
getKind원시 타입, Unit 타입의 경우 KSBuiltIns의 타입과 비교하고, 그렇지 않으면 선언된 타입과 비교

TypeVariable ​

JavaKSP 해당 기능
asElementksType.declaration
getLowerBound결정 예정. 캡처(capture)가 제공되고 명시적인 바운드 검사가 필요한 경우에만 필요함.
getUpperBoundksTypeParameter.bounds

WildcardType ​

JavaKSP 해당 기능
getExtendsBound
kotlin
if (ksTypeArgument.variance == Variance.COVARIANT) ksTypeArgument.type else null
getSuperBound
kotlin
if (ksTypeArgument.variance == Variance.CONTRAVARIANT) ksTypeArgument.type else null

Elements ​

JavaKSP 해당 기능
getAllAnnotationMirrorsKSDeclarations.annotations
getAllMembersgetAllFunctions, getAllProperties 구현 예정
getBinaryName결정 예정, Java 사양(Specification) 참조
getConstantExpression표현식이 아닌 상수 값이 존재함
getDocComment구현 예정
getElementValuesWithDefaults구현 예정
getNameresolver.getKSNameFromString
getPackageElement패키지는 지원되지 않지만, 패키지 정보는 가져올 수 있습니다. KSP에서는 패키지에 대한 작업이 불가능합니다.
getPackageOf패키지 지원 안 됨
getTypeElementResolver.getClassDeclarationByName
hides구현 예정
isDeprecated
kotlin
KsDeclaration.annotations.any { 
    it.annotationType.resolve()!!.declaration.qualifiedName!!.asString() == Deprecated::class.qualifiedName
}
overridesKSFunctionDeclaration.overrides / KSPropertyDeclaration.overrides (각 클래스의 멤버 함수)
printElementsKSP는 대부분의 클래스에 기본 toString() 구현을 가지고 있음

타입 작업 (Types) ​

JavaKSP 해당 기능
asElementksType.declaration
asMemberOfresolver.asMemberOf
boxedClass필요하지 않음
capture결정 예정
containsKSType.isAssignableFrom
directSuperTypes(ksType.declaration as KSClassDeclaration).superTypes
erasureksType.starProjection()
getArrayTypeksBuiltIns.arrayType.replace(...)
getDeclaredTypeksClassDeclaration.asType
getNoTypeksBuiltIns.nothingType / null
getNullType컨텍스트에 따라 KSType.markNullable이 유용할 수 있음
getPrimitiveType필요하지 않음, KSBuiltins 확인
getWildcardTypeKSTypeArgument가 필요한 곳에 Variance 사용
isAssignableksType.isAssignableFrom
isSameTypeksType.equals
isSubsignaturefunctionTypeA == functionTypeB / functionTypeA == functionTypeB.starProjection()
isSubtypeksType.isAssignableFrom
unboxedType필요하지 않음