Merge pull request eclipse-lsp4j#273 from kittaakos/eclipse-lsp4jGH-272

eclipse-lsp4jGH-272: Updated the API to support type hierarchies.

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/Protocol.xtend

@@ -752,6 +752,7 @@ class FoldingRangeCapabilities extends DynamicRegistrationCapabilities {
 /**
  * Capabilities specific to {@code textDocument/semanticHighlighting}.
  */
+@Beta
 @JsonRpcData
 class SemanticHighlightingCapabilities {
 	/**
@@ -767,6 +768,28 @@ class SemanticHighlightingCapabilities {
 	}
 }
 
+/**
+ * Capabilities specific to the {@code textDocument/typeHierarchy} and the {@code typeHierarchy/resolve}
+ * language server methods.
+ */
+@Beta
+@JsonRpcData
+class TypeHierarchyCapabilities {
+
+	/**
+	 * The language client supports super- and subtype hierarchies.
+	 */
+	Boolean typeHierarchy
+
+	new() {
+	}
+
+	new(Boolean typeHierarchy) {
+		this.typeHierarchy = typeHierarchy
+	}
+
+}
+
 /**
  * Text document specific client capabilities.
  */
@@ -881,7 +904,14 @@ class TextDocumentClientCapabilities {
 	/**
 	 * Capabilities specific to {@code textDocument/semanticHighlighting}.
 	 */
+	@Beta
 	SemanticHighlightingCapabilities semanticHighlightingCapabilities
+
+	/**
+	 * Capabilities specific to {@code textDocument/typeHierarchy}.
+	 */
+	@Beta
+	TypeHierarchyCapabilities typeHierarchyCapabilities
 }
 
 /**
@@ -1982,6 +2012,70 @@ class DocumentRangeFormattingParams extends DocumentFormattingParams {
 	}
 }
 
+/**
+ * The type hierarchy request is sent from the client resolve a {@link TypeHierarchyItem type hierarchy item} for
+ * a give cursor location in the text document. The request would also allow to specify if the item should be resolved
+ * and whether sub- or supertypes are to be resolved.
+ */
+@JsonRpcData
+class TypeHierarchyParams extends TextDocumentPositionParams {
+
+	/**
+	 * The number of hierarchy levels to resolve. {@code 0} indicates no hierarchy level. It defaults to {@code 0}.
+	 */
+	int resolve
+
+	/**
+	 * The direction of the type hierarchy resolution. If not defined, defaults to {@code children}.
+	 * 
+	 * <p>
+	 * The followings are the legal values:
+	 * <ul>
+	 * <li>{@code children},</li>
+	 * <li>{@code parents}, and</li>
+	 * <li>{@code both}.</li>
+	 * </ul>
+	 * </p>
+	 */
+	String direction
+}
+
+/**
+ * Request to resolve an unresolved {@link TypeHierarchyItem type hierarchy item} which is indicated if the
+ * {@link TypeHierarchyItem#getParents parents} or the {@link TypeHierarchyItem#getChildren children} is not
+ * defined. If resolved and no {@code parents} or {@code children} are available then an empty list is returned.
+ */
+@JsonRpcData
+class ResolveTypeHierarchyItemParams {
+
+	/**
+	 * The hierarchy item to resolve.
+	 */
+	@NonNull
+	TypeHierarchyItem item
+
+	/**
+	 * The number of hierarchy levels to resolve. {@code 0} indicates no hierarchy level.
+	 */
+	int resolve
+
+	/**
+	 * The direction of the type hierarchy resolution.
+	 * 
+	 * <p>
+	 * The followings are the legal values:
+	 * <ul>
+	 * <li>{@code children},</li>
+	 * <li>{@code parents}, and</li>
+	 * <li>{@code both}.</li>
+	 * </ul>
+	 * </p>
+	 */
+	@NonNull
+	String direction
+
+}
+
 /**
  * The document symbol request is sent from the client to the server to list all symbols found in a given text document.
  */
@@ -2743,7 +2837,13 @@ class ServerCapabilities {
 	/**
 	 * Semantic highlighting server capabilities.
 	 */
-	SemanticHighlightingServerCapabilities semanticHighlighting;
+	SemanticHighlightingServerCapabilities semanticHighlighting
+
+	/**
+	 * Server capability for calculating super- and subtype hierarchies.
+	 * The LS supports the type hierarchy language feature, if this capability is set to {@code true}.
+	 */
+	Boolean typeHierarchy
 
 	/**
 	 * Experimental server capabilities.
@@ -2922,6 +3022,79 @@ class SignatureInformation {
 	}
 }
 
+/**
+ * Representation of an item that carries type information (such as class, interface, enumeration, etc) with additional parentage details.
+ */
+@JsonRpcData
+class TypeHierarchyItem {
+
+	/**
+	 * The human readable name of the hierarchy item.
+	 */
+	@NonNull
+	String name
+
+	/**
+	 * Optional detail for the hierarchy item. It can be, for instance, the signature of a function or method.
+	 */
+	String detail
+
+	/**
+	 * The kind of the hierarchy item. For instance, class or interface.
+	 */
+	@NonNull
+	SymbolKind kind
+
+	/**
+	 * {@code true} if the hierarchy item is deprecated. Otherwise, {@code false}. It is {@code false} by default.
+	 */
+	Boolean deprecated
+
+	/**
+	 * The URI of the text document where this type hierarchy item belongs to.
+	 */
+	@NonNull
+	String uri
+
+	/**
+	 * The range enclosing this type hierarchy item not including leading/trailing whitespace but everything else
+	 * like comments. This information is typically used to determine if the the clients cursor is inside the type
+	 * hierarchy item to reveal in the symbol in the UI.
+	 * 
+	 * @see TypeHierarchyItem#selectionRange
+	 */
+	@NonNull
+	Range range
+
+	/**
+	 * The range that should be selected and revealed when this type hierarchy item is being picked, e.g the name of a function.
+	 * Must be contained by the the {@link TypeHierarchyItem#getRange range}.
+	 * 
+	 * @see TypeHierarchyItem#range
+	 */
+	@NonNull
+	Range selectionRange
+
+	/**
+	 * If this type hierarchy item is resolved, it contains the direct parents. Could be empty if the item does not have any
+	 * direct parents. If not defined, the parents have not been resolved yet.
+	 */
+	List<TypeHierarchyItem> parents
+
+	/**
+	 * If this type hierarchy item is resolved, it contains the direct children of the current item.
+	 * Could be empty if the item does not have any descendants. If not defined, the children have not been resolved.
+	 */
+	List<TypeHierarchyItem> children
+
+	/**
+	 * An optional data field can be used to identify a type hierarchy item in a resolve request.
+	 */
+	@JsonAdapter(JsonElementTypeAdapter.Factory)
+	Object data
+
+}
+
 /**
  * Represents programming constructs like variables, classes, interfaces etc. that appear in a document. Document symbols can be
  * hierarchical and they have two ranges: one that encloses its definition and one that points to its most interesting range,

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/services/TextDocumentService.java

@@ -47,11 +47,14 @@
 import org.eclipse.lsp4j.Range;
 import org.eclipse.lsp4j.ReferenceParams;
 import org.eclipse.lsp4j.RenameParams;
+import org.eclipse.lsp4j.ResolveTypeHierarchyItemParams;
 import org.eclipse.lsp4j.SignatureHelp;
 import org.eclipse.lsp4j.SymbolInformation;
 import org.eclipse.lsp4j.TextDocumentPositionParams;
 import org.eclipse.lsp4j.TextDocumentRegistrationOptions;
 import org.eclipse.lsp4j.TextEdit;
+import org.eclipse.lsp4j.TypeHierarchyItem;
+import org.eclipse.lsp4j.TypeHierarchyParams;
 import org.eclipse.lsp4j.WillSaveTextDocumentParams;
 import org.eclipse.lsp4j.WorkspaceEdit;
 import org.eclipse.lsp4j.adapters.CodeActionResponseAdapter;
@@ -63,6 +66,8 @@
 import org.eclipse.lsp4j.jsonrpc.services.JsonRequest;
 import org.eclipse.lsp4j.jsonrpc.services.JsonSegment;
 
+import com.google.common.annotations.Beta;
+
 @JsonSegment("textDocument")
 public interface TextDocumentService {
 
@@ -353,7 +358,7 @@ default CompletableFuture<DocumentLink> documentLinkResolve(DocumentLink params)
 	}
 
 	/**
-	 * The document color request is sent from the client to the server to list all color refereces found in a given text
+	 * The document color request is sent from the client to the server to list all color references found in a given text
 	 * document. Along with the range, a color value in RGB is returned.
 	 * 
 	 * Clients can use the result to decorate color references in an editor. For example:
@@ -402,4 +407,32 @@ default CompletableFuture<List<FoldingRange>> foldingRange(FoldingRangeRequestPa
 	default CompletableFuture<Either<Range, PrepareRenameResult>> prepareRename(TextDocumentPositionParams params) {
 		throw new UnsupportedOperationException();
 	}
+
+	/**
+	 * The {@code textDocument/typeHierarchy} request is sent from the client to the
+	 * server to retrieve a {@link TypeHierarchyItem type hierarchy item} based on
+	 * the {@link TypeHierarchyParams cursor position in the text document}. This
+	 * request would also allow to specify if the item should be resolved and
+	 * whether sub- or supertypes are to be resolved. If no type hierarchy item can
+	 * be found under the given text document position, resolves to {@code null}.
+	 */
+	@Beta
+	@JsonRequest
+	default CompletableFuture<TypeHierarchyItem> typeHierarchy(TypeHierarchyParams params) {
+		throw new UnsupportedOperationException();
+	}
+
+	/**
+	 * The {@code typeHierarchy/resolve} request is sent from the client to the
+	 * server to resolve an unresolved {@link TypeHierarchyItem type hierarchy
+	 * item}. A type hierarchy item is unresolved if the if the
+	 * {@link TypeHierarchyItem#getParents parents} or the
+	 * {@link TypeHierarchyItem#getChildren children} is not defined.
+	 */
+	@Beta
+	@JsonRequest(value="typeHierarchy/resolve", useSegment = false)
+	default CompletableFuture<TypeHierarchyItem> resolveTypeHierarchy(ResolveTypeHierarchyItemParams params) {
+		throw new UnsupportedOperationException();
+	}
+
 }

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/util/Positions.java

@@ -21,7 +21,7 @@
 public final class Positions {
 
 	/**
-	 * {@code true} if {@left} is strictly before than {@code right}. Otherwise,
+	 * {@code true} if {@code left} is strictly before than {@code right}. Otherwise,
 	 * {@code false}.
 	 * <p>
 	 * If you want to allow equality, use {@link Position#equals}.

org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/util/SemanticHighlightingTokens.java

@@ -131,7 +131,7 @@ public static int[] toIntArray(Iterable<? extends Token> tokens) {
 		 * 
 		 * The elements of the input will be used to create new {@link Token} instances,
 		 * hence they must comply the requirements described
-		 * {@link #Token(int, int, int) here}.
+		 * {@link #SemanticHighlightingTokens.Token(int, int, int) here}.
 		 */
 		public static List<Token> fromIntArray(int... input) {
 			if (input == null) {