JvmDeclarationUElement: separates UElement.sourcePsi and javaPsi

`JvmDeclarationUElement` is a temporary replacement for `UElement`

plugins/groovy/groovy-psi/src/org/jetbrains/plugins/groovy/lang/psi/uast/GroovyDummyUastPlugin.kt

@@ -52,7 +52,7 @@ class GroovyDummyUastPlugin : UastLanguagePlugin {
 
 }
 
-class GrULiteral(val grElement: GrLiteral, val parentProvider: () -> UElement?) : ULiteralExpression {
+class GrULiteral(val grElement: GrLiteral, val parentProvider: () -> UElement?) : ULiteralExpression, JvmDeclarationUElement {
   override val value: Any?
     get() = grElement.value
   override val uastParent by lazy(parentProvider)
@@ -60,7 +60,7 @@ class GrULiteral(val grElement: GrLiteral, val parentProvider: () -> UElement?)
   override val annotations: List<UAnnotation> = emptyList() //not implemented
 }
 
-class GrUNamedExpression(val grElement: GrAnnotationNameValuePair, val parentProvider: () -> UElement?) : UNamedExpression {
+class GrUNamedExpression(val grElement: GrAnnotationNameValuePair, val parentProvider: () -> UElement?) : UNamedExpression, JvmDeclarationUElement {
   override val name: String?
     get() = grElement.name
   override val expression: UExpression
@@ -73,7 +73,7 @@ class GrUNamedExpression(val grElement: GrAnnotationNameValuePair, val parentPro
 
 }
 
-class GrUAnnotation(val grElement: GrAnnotation, val parentProvider: () -> UElement?) : UAnnotation {
+class GrUAnnotation(val grElement: GrAnnotation, val parentProvider: () -> UElement?) : UAnnotation, JvmDeclarationUElement {
   override val qualifiedName: String?
     get() = grElement.qualifiedName
 
@@ -95,7 +95,7 @@ class GrUAnnotation(val grElement: GrAnnotation, val parentProvider: () -> UElem
 
 }
 
-class GrUnknownUExpression(override val psi: PsiElement?, override val uastParent: UElement?) : UExpression {
+class GrUnknownUExpression(override val psi: PsiElement?, override val uastParent: UElement?) : UExpression, JvmDeclarationUElement {
 
   override fun asLogString(): String = "GrUnknownUExpression(grElement)"
 

uast/uast-common/src/org/jetbrains/uast/baseElements/UComment.kt

@@ -19,7 +19,7 @@ import com.intellij.psi.PsiComment
 import com.intellij.psi.PsiElement
 import org.jetbrains.uast.internal.log
 
-class UComment(override val psi: PsiComment, override val uastParent: UElement) : UElement {
+class UComment(override val psi: PsiComment, override val uastParent: UElement) : JvmDeclarationUElement {
     @Deprecated("Use a constructor that takes PsiComment as parameter")
     constructor(psi: PsiElement, parent: UElement) : this(psi as PsiComment, parent)
 

uast/uast-common/src/org/jetbrains/uast/baseElements/UElement.kt

@@ -101,6 +101,38 @@ interface UElement {
     fun <D, R> accept(visitor: UastTypedVisitor<D, R>, data: D): R = visitor.visitElement(this, data)
 }
 
+/**
+ * This is transitional type, all its content will be moved to `UElement` as soon as all implementations will implement it,
+ * and someday this interface will be dropped.
+ */
+interface JvmDeclarationUElement : UElement {
+
+    /**
+     * Returns the PSI element in original (physical) tree to which this UElement corresponds.
+     * **Note**: that some UElements are synthetic and do not have an underlying PSI element;
+     * this doesn't mean that they are invalid.
+     */
+    val sourcePsi: PsiElement?
+        get() = psi
+
+    /**
+     * Returns the element which try to mimic Java-api psi element: [com.intellij.psi.PsiClass], [com.intellij.psi.PsiMethod] or [com.intellij.psi.PsiAnnotation] etc.
+     * Will return null if this UElement doesn't have Java representation or it is not implemented.
+     */
+    val javaPsi: PsiElement?
+        get() = psi
+
+    /**
+     * Returns the PSI element underlying this element. Note that some UElements are synthetic and do not have
+     * an underlying PSI element; this doesn't mean that they are invalid.
+     *
+     * **Node for implementors**: please implement both [sourcePsi] and [javaPsi] fields or make them return `null` explicitly
+     * if implementing is not possible. Redirect `psi` to one of them keeping existing behavior, use [sourcePsi] if nothing else is specified.
+     */
+    @Deprecated("ambiguous psi element, use `sourcePsi` or `javaPsi`", ReplaceWith("javaPsi"))
+    override val psi: PsiElement?
+}
+
 /**
  * Returns a sequence including this element and its containing elements.
  */

uast/uast-common/src/org/jetbrains/uast/baseElements/UExpression.kt

@@ -84,7 +84,7 @@ interface ULabeled : UElement {
  *
  * Use [UastEmptyExpression] in this case.
  */
-object UastEmptyExpression : UExpression {
+object UastEmptyExpression : UExpression, JvmDeclarationUElement {
     override val uastParent: UElement?
         get() = null
 

uast/uast-common/src/org/jetbrains/uast/baseElements/UIdentifier.kt

@@ -22,7 +22,7 @@ import org.jetbrains.uast.internal.log
 class UIdentifier(
         override val psi: PsiElement?,
         override val uastParent: UElement?
-) : UElement {
+) : JvmDeclarationUElement {
     /**
      * Returns the identifier name.
      */

uast/uast-common/src/org/jetbrains/uast/declarations/UDeclaration.kt

@@ -28,7 +28,7 @@ interface UDeclaration : UElement, PsiModifierListOwner, UAnnotated {
      * Returns the original declaration (which is *always* unwrapped, never a [UDeclaration]).
      */
     override val psi: PsiModifierListOwner
-    
+
     override fun getOriginalElement(): PsiElement? = psi.originalElement
 
     /**

uast/uast-java/src/org/jetbrains/uast/java/JavaAbstractUElement.kt

@@ -17,14 +17,11 @@
 package org.jetbrains.uast.java
 
 import com.intellij.psi.*
-import org.jetbrains.uast.UAnnotation
-import org.jetbrains.uast.UElement
-import org.jetbrains.uast.UExpression
+import org.jetbrains.uast.*
 import org.jetbrains.uast.java.internal.JavaUElementWithComments
-import org.jetbrains.uast.toUElement
 
 
-abstract class JavaAbstractUElement(givenParent: UElement?) : JavaUElementWithComments {
+abstract class JavaAbstractUElement(givenParent: UElement?) : JavaUElementWithComments, JvmDeclarationUElement {
 
     @Suppress("unused") // Used in Kotlin 1.2, to be removed in 2018.1
     @Deprecated("use JavaAbstractUElement(givenParent)", ReplaceWith("JavaAbstractUElement(givenParent)"))
@@ -53,7 +50,16 @@ abstract class JavaAbstractUElement(givenParent: UElement?) : JavaUElementWithCo
       }
 
     protected open fun getPsiParentForLazyConversion() = this.psi?.parent
-}
+
+    //explicitly overridden in abstract class to be binary compatible with Kotlin
+    override val comments: List<UComment>
+        get() = super<JavaUElementWithComments>.comments
+    override val sourcePsi: PsiElement?
+        get() = super.sourcePsi
+    override val javaPsi: PsiElement?
+        get() = super.javaPsi
+
+   }
 
 abstract class JavaAbstractUExpression(givenParent: UElement?) : JavaAbstractUElement(givenParent), UExpression {
 

uast/uast-java/src/org/jetbrains/uast/java/controlStructures/JavaUSwitchExpression.kt

@@ -100,7 +100,7 @@ class JavaUSwitchEntry(
     }
 }
 
-object JavaUDefaultCaseExpression : UExpression {
+object JavaUDefaultCaseExpression : UExpression, JvmDeclarationUElement {
     override val uastParent: UElement?
         get() = null
 

uast/uast-java/src/org/jetbrains/uast/java/declarations/JavaUClass.kt

@@ -61,7 +61,11 @@ abstract class AbstractJavaUClass(givenParent: UElement?) : JavaAbstractUElement
 
 class JavaUClass private constructor(psi: PsiClass, override val uastParent: UElement?) :
         AbstractJavaUClass(uastParent), PsiClass by psi {
-    override val psi = unwrap<UClass, PsiClass>(psi)
+
+    override val psi: PsiClass
+        get() = javaPsi
+
+    override val javaPsi: PsiClass = unwrap<UClass, PsiClass>(psi)
 
     override fun getSuperClass(): UClass? = super.getSuperClass()
     override fun getFields(): Array<UField> = super.getFields()
@@ -83,7 +87,10 @@ class JavaUAnonymousClass(
         psi: PsiAnonymousClass,
         uastParent: UElement?
 ) : AbstractJavaUClass(uastParent), UAnonymousClass, PsiAnonymousClass by psi {
-    override val psi: PsiAnonymousClass = unwrap<UAnonymousClass, PsiAnonymousClass>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi: PsiAnonymousClass = unwrap<UAnonymousClass, PsiAnonymousClass>(psi)
 
     override fun getSuperClass(): UClass? = super<AbstractJavaUClass>.getSuperClass()
     override fun getFields(): Array<UField> = super<AbstractJavaUClass>.getFields()

uast/uast-java/src/org/jetbrains/uast/java/declarations/JavaUClassInitializer.kt

@@ -24,7 +24,10 @@ class JavaUClassInitializer(
         psi: PsiClassInitializer,
         uastParent: UElement?
 ) : JavaAbstractUElement(uastParent), UClassInitializer, JavaUElementWithComments, PsiClassInitializer by psi {
-    override val psi = unwrap<UClassInitializer, PsiClassInitializer>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<UClassInitializer, PsiClassInitializer>(psi)
 
     override val uastAnchor: UElement?
         get() = null

uast/uast-java/src/org/jetbrains/uast/java/declarations/JavaUFile.kt

@@ -18,13 +18,10 @@ package org.jetbrains.uast.java
 import com.intellij.psi.PsiComment
 import com.intellij.psi.PsiJavaFile
 import com.intellij.psi.PsiRecursiveElementWalkingVisitor
-import org.jetbrains.uast.UAnnotation
-import org.jetbrains.uast.UComment
-import org.jetbrains.uast.UFile
-import org.jetbrains.uast.UastLanguagePlugin
+import org.jetbrains.uast.*
 import java.util.*
 
-class JavaUFile(override val psi: PsiJavaFile, override val languagePlugin: UastLanguagePlugin) : UFile {
+class JavaUFile(override val psi: PsiJavaFile, override val languagePlugin: UastLanguagePlugin) : UFile, JvmDeclarationUElement {
     override val packageName: String
         get() = psi.packageName
     

uast/uast-java/src/org/jetbrains/uast/java/declarations/JavaUImportStatement.kt

@@ -16,13 +16,14 @@
 package org.jetbrains.uast.java
 
 import com.intellij.psi.PsiImportStatementBase
+import org.jetbrains.uast.JvmDeclarationUElement
 import org.jetbrains.uast.UElement
 import org.jetbrains.uast.UImportStatement
 
 class JavaUImportStatement(
         override val psi: PsiImportStatementBase, 
         uastParent: UElement?
-) : JavaAbstractUElement(uastParent), UImportStatement {
+) : JavaAbstractUElement(uastParent), UImportStatement, JvmDeclarationUElement {
     override val isOnDemand: Boolean
         get() = psi.isOnDemand
     override val importReference by lz { psi.importReference?.let { JavaDumbUElement(it, this, it.qualifiedName) } }

uast/uast-java/src/org/jetbrains/uast/java/declarations/JavaUMethod.kt

@@ -26,7 +26,10 @@ open class JavaUMethod(
         psi: PsiMethod,
         uastParent: UElement?
 ) : JavaAbstractUElement(uastParent), UMethod, JavaUElementWithComments, PsiMethod by psi {
-    override val psi = unwrap<UMethod, PsiMethod>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<UMethod, PsiMethod>(psi)
     
     override val uastBody by lz {
         val body = psi.body ?: return@lz null
@@ -61,6 +64,10 @@ class JavaUAnnotationMethod(
         languagePlugin: UastLanguagePlugin,
         containingElement: UElement?
 ) : JavaUMethod(psi, containingElement), UAnnotationMethod {
+
+    override val javaPsi: PsiAnnotationMethod
+        get() = psi
+
     override val uastDefaultValue by lz {
         val defaultValue = psi.defaultValue ?: return@lz null
         languagePlugin.convertElement(defaultValue, this, null) as? UExpression

uast/uast-java/src/org/jetbrains/uast/java/declarations/JavaUVariable.kt

@@ -22,6 +22,8 @@ import org.jetbrains.uast.java.internal.JavaUElementWithComments
 
 abstract class AbstractJavaUVariable(givenParent: UElement?) : JavaAbstractUElement(givenParent), PsiVariable, UVariable, JavaUElementWithComments {
 
+    abstract override val javaPsi: PsiVariable
+
     @Suppress("unused") // Used in Kotlin 1.1.4, to be removed in 2018.1
     @Deprecated("use AbstractJavaUVariable(givenParent) instead", ReplaceWith("AbstractJavaUVariable(givenParent)"))
     constructor() : this(null)
@@ -45,7 +47,10 @@ open class JavaUVariable(
         psi: PsiVariable,
         givenParent: UElement?
 ) : AbstractJavaUVariable(givenParent), UVariable, PsiVariable by psi {
-    override val psi = unwrap<UVariable, PsiVariable>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<UVariable, PsiVariable>(psi)
     
     companion object {
         fun create(psi: PsiVariable, containingElement: UElement?): UVariable {
@@ -64,21 +69,30 @@ open class JavaUParameter(
         psi: PsiParameter,
         givenParent: UElement?
 ) : AbstractJavaUVariable(givenParent), UParameter, PsiParameter by psi {
-    override val psi = unwrap<UParameter, PsiParameter>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<UParameter, PsiParameter>(psi)
 }
 
 open class JavaUField(
         psi: PsiField,
         givenParent: UElement?
 ) : AbstractJavaUVariable(givenParent), UField, PsiField by psi {
-    override val psi = unwrap<UField, PsiField>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<UField, PsiField>(psi)
 }
 
 open class JavaULocalVariable(
         psi: PsiLocalVariable,
         givenParent: UElement?
 ) : AbstractJavaUVariable(givenParent), ULocalVariable, PsiLocalVariable by psi {
-    override val psi = unwrap<ULocalVariable, PsiLocalVariable>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<ULocalVariable, PsiLocalVariable>(psi)
 }
 
 open class JavaUEnumConstant(
@@ -87,7 +101,10 @@ open class JavaUEnumConstant(
 ) : AbstractJavaUVariable(givenParent), UEnumConstant, PsiEnumConstant by psi {
     override val initializingClass: UClass? by lz { getLanguagePlugin().convertOpt<UClass>(psi.initializingClass, this) }
 
-    override val psi = unwrap<UEnumConstant, PsiEnumConstant>(psi)
+    override val psi
+        get() = javaPsi
+
+    override val javaPsi = unwrap<UEnumConstant, PsiEnumConstant>(psi)
 
     override val kind: UastCallKind
         get() = UastCallKind.CONSTRUCTOR_CALL

uast/uast-java/src/org/jetbrains/uast/java/expressions/JavaDumbUElement.kt

@@ -16,6 +16,7 @@
 package org.jetbrains.uast.java
 
 import com.intellij.psi.PsiElement
+import org.jetbrains.uast.JvmDeclarationUElement
 import org.jetbrains.uast.UElement
 import org.jetbrains.uast.internal.log
 
@@ -23,7 +24,7 @@ class JavaDumbUElement(
         override val psi: PsiElement,
         givenParent: UElement?,
         private val customRenderString: String? = null
-) : JavaAbstractUElement(givenParent), UElement {
+) : JavaAbstractUElement(givenParent), JvmDeclarationUElement {
     override fun asLogString() = log()
     override fun asRenderString() = customRenderString ?: "<stub@$psi>"
 }

uast/uast-java/src/org/jetbrains/uast/java/expressions/JavaUDeclarationsExpression.kt

@@ -16,14 +16,11 @@
 package org.jetbrains.uast.java
 
 import com.intellij.psi.PsiElement
-import org.jetbrains.uast.UAnnotation
-import org.jetbrains.uast.UDeclaration
-import org.jetbrains.uast.UDeclarationsExpression
-import org.jetbrains.uast.UElement
+import org.jetbrains.uast.*
 
 class JavaUDeclarationsExpression(
         uastParent: UElement?
-) : JavaAbstractUElement(uastParent), UDeclarationsExpression {
+) : JavaAbstractUElement(uastParent), UDeclarationsExpression, JvmDeclarationUElement {
     override lateinit var declarations: List<UDeclaration>
         internal set
 

uast/uast-java/src/org/jetbrains/uast/java/expressions/UnknownJavaExpression.kt

@@ -16,6 +16,7 @@
 package org.jetbrains.uast.java
 
 import com.intellij.psi.PsiElement
+import org.jetbrains.uast.JvmDeclarationUElement
 import org.jetbrains.uast.UAnnotation
 import org.jetbrains.uast.UElement
 import org.jetbrains.uast.UExpression
@@ -23,7 +24,7 @@ import org.jetbrains.uast.UExpression
 class UnknownJavaExpression(
         override val psi: PsiElement,
         uastParent: UElement?
-) : JavaAbstractUElement(uastParent), UExpression {
+) : JavaAbstractUElement(uastParent), UExpression, JvmDeclarationUElement {
     override fun asLogString() = "[!] " + UnknownJavaExpression::class.java.simpleName + " ($psi)"
 
     override val annotations: List<UAnnotation>