Skip to content

Commit 9b5b259

Browse files
jonahgrahamjonahgraham
committed
Remove @Deprecated from members that are deprecated in protocol
The LSP4J project does not use standard Deprecated annotation when implementing LSP/DAP specification as it leads to unresolvable deprecation warnings. The standard Deprecated annotation should be used in LSP4J for LSP4J's own API that is not directly implementing the protocol specification. This commit introduces `@ProtocolDeprecated` as an annotation to make it easier for API consumers to identify areas that the underlying LSP/DAP have deprecated. Fixes #895
1 parent 8b4a248 commit 9b5b259

File tree

5 files changed

+85
-46
lines changed

5 files changed

+85
-46
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
Fixed issues: <https://github.com/eclipse-lsp4j/lsp4j/milestone/37?closed=1>
66

7+
* Removed `@Deprecated` annotations on members deprecated in the LSP/DAP protocol [#895](https://github.com/eclipse-lsp4j/lsp4j/issues/895)
8+
79
Breaking API changes:
810

911
* Removed deprecated API [#874](https://github.com/eclipse-lsp4j/lsp4j/issues/874)

‎org.eclipse.lsp4j.debug/src/main/java/org/eclipse/lsp4j/debug/DebugProtocol.xtend‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import com.google.gson.annotations.SerializedName
1717
import java.util.Map
1818
import org.eclipse.lsp4j.debug.adapters.RestartArgumentsArgumentsTypeAdapter
1919
import org.eclipse.lsp4j.generator.JsonRpcData
20+
import org.eclipse.lsp4j.jsonrpc.ProtocolDeprecated
2021
import org.eclipse.lsp4j.jsonrpc.messages.Either
2122
import org.eclipse.lsp4j.jsonrpc.validation.NonNull
2223

@@ -1154,10 +1155,10 @@ class SetBreakpointsArguments {
11541155
* The code locations of the breakpoints.
11551156
* <p>
11561157
* This is an optional property.
1157-
*
1158-
* @deprecated Use {@link SourceBreakpoint#line} of {@link #breakpoints} instead.
1158+
* <p>
1159+
* Deprecated in DAP: Use {@link SourceBreakpoint#line} of {@link #breakpoints} instead.
11591160
*/
1160-
@Deprecated
1161+
@ProtocolDeprecated
11611162
int[] lines;
11621163
/**
11631164
* A value of true indicates that the underlying source has been modified which results in new breakpoint
@@ -3746,10 +3747,10 @@ interface VariablePresentationHintKind {
37463747
public static final String VIRTUAL = "virtual";
37473748
/**
37483749
* Indicates that a data breakpoint is registered for the object.
3749-
*
3750-
* @deprecated The {@link VariablePresentationHintAttributes#HAS_DATA_BREAKPOINT} attribute should generally be used instead.
3750+
* <p>
3751+
* Deprecated in DAP: The {@link VariablePresentationHintAttributes#HAS_DATA_BREAKPOINT} attribute should generally be used instead.
37513752
*/
3752-
@Deprecated
3753+
@ProtocolDeprecated
37533754
public static final String DATA_BREAKPOINT = "dataBreakpoint";
37543755
}
37553756

‎org.eclipse.lsp4j.jsonrpc/src/main/java/org/eclipse/lsp4j/jsonrpc/ProtocolDeprecated.java‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
/**
2+
* Copyright (c) 2025 Kichwa Coders Canada, Inc.
3+
*
4+
* This program and the accompanying materials are made available under the
5+
* terms of the Eclipse Public License v. 2.0 which is available at
6+
* http://www.eclipse.org/legal/epl-2.0,
7+
* or the Eclipse Distribution License v. 1.0 which is available at
8+
* http://www.eclipse.org/org/documents/edl-v10.php.
9+
*
10+
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
11+
*/
12+
package org.eclipse.lsp4j.jsonrpc;
13+
14+
import java.lang.annotation.Documented;
15+
import java.lang.annotation.ElementType;
16+
import java.lang.annotation.Retention;
17+
import java.lang.annotation.RetentionPolicy;
18+
import java.lang.annotation.Target;
19+
20+
/**
21+
* An API using this annotation is part of a Protocol Specification and is deprecated in the protocol.
22+
* Therefore it is subject to removal in a future release.
23+
* <p>
24+
* This is synonymous with Java's standard {@link Deprecated} annotation, however the LSP4J project
25+
* does not use standard Deprecated annotation when implementing LSP/DAP specification as it leads
26+
* to unresolvable deprecation warnings. The standard Deprecated annotation should be used in LSP4J
27+
* for LSP4J's own API that is not directly implementing the protocol specification.
28+
*/
29+
@Retention(RetentionPolicy.CLASS)
30+
@Target({
31+
ElementType.CONSTRUCTOR,
32+
ElementType.FIELD,
33+
ElementType.METHOD,
34+
ElementType.TYPE
35+
})
36+
@Documented
37+
public @interface ProtocolDeprecated {}

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

Lines changed: 36 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ import org.eclipse.lsp4j.jsonrpc.messages.ResponseErrorCode
3737
import org.eclipse.lsp4j.jsonrpc.messages.Tuple
3838
import org.eclipse.lsp4j.jsonrpc.util.Preconditions
3939
import org.eclipse.lsp4j.jsonrpc.validation.NonNull
40+
import org.eclipse.lsp4j.jsonrpc.ProtocolDeprecated
4041

4142
@JsonRpcData
4243
class DynamicRegistrationCapabilities {
@@ -2956,10 +2957,10 @@ class CompletionItem {
29562957
* Indicates if this item is deprecated.
29572958
* <p>
29582959
* Since 3.8.0
2959-
*
2960-
* @deprecated Use {@link #tags} instead if supported.
2960+
* <p>
2961+
* Deprecated in LSP: Use {@link #tags} instead if supported.
29612962
*/
2962-
@Deprecated
2963+
@ProtocolDeprecated
29632964
Boolean deprecated
29642965

29652966
/**
@@ -4505,11 +4506,11 @@ class Hover {
45054506
* </pre>
45064507
* <p>
45074508
* Note that markdown strings will be sanitized - that means html will be escaped.
4508-
*
4509-
* @deprecated Use {@link MarkupContent} instead.
4509+
* <p>
4510+
* Deprecated in LSP: Use {@link MarkupContent} instead.
45104511
*/
45114512
@JsonRpcData
4512-
@Deprecated
4513+
@ProtocolDeprecated
45134514
class MarkedString {
45144515
@NonNull
45154516
String language
@@ -4854,11 +4855,11 @@ class InitializeError {
48544855
interface InitializeErrorCode {
48554856
/**
48564857
* If the protocol version provided by the client can't be handled by the server.
4857-
*
4858-
* @deprecated This initialize error got replaced by client capabilities.
4858+
* <p>
4859+
* Deprecated in LSP: This initialize error got replaced by client capabilities.
48594860
* There is no version handshake in version 3.0x
48604861
*/
4861-
@Deprecated
4862+
@ProtocolDeprecated
48624863
val unknownProtocolVersion = 1
48634864
}
48644865

@@ -4880,19 +4881,19 @@ class InitializeParams implements WorkDoneProgressParams {
48804881

48814882
/**
48824883
* The rootPath of the workspace. Is null if no folder is open.
4883-
*
4884-
* @deprecated Use {@link #workspaceFolders} instead.
4884+
* <p>
4885+
* Deprecated in LSP: Use {@link #workspaceFolders} instead.
48854886
*/
4886-
@Deprecated
4887+
@ProtocolDeprecated
48874888
String rootPath
48884889

48894890
/**
48904891
* The rootUri of the workspace. Is null if no folder is open.
48914892
* If both {@link #rootPath} and `rootUri` are set, `rootUri` wins.
4892-
*
4893-
* @deprecated Use {@link #workspaceFolders} instead.
4893+
* <p>
4894+
* Deprecated in LSP: Use {@link #workspaceFolders} instead.
48944895
*/
4895-
@Deprecated
4896+
@ProtocolDeprecated
48964897
String rootUri
48974898

48984899
/**
@@ -6601,10 +6602,10 @@ class DocumentSymbol {
66016602

66026603
/**
66036604
* Indicates if this symbol is deprecated.
6604-
*
6605-
* @deprecated Use {@link #tags} instead if supported.
6605+
* <p>
6606+
* Deprecated in LSP: Use {@link #tags} instead if supported.
66066607
*/
6607-
@Deprecated
6608+
@ProtocolDeprecated
66086609
Boolean deprecated
66096610

66106611
/**
@@ -6638,46 +6639,43 @@ class DocumentSymbol {
66386639

66396640
/**
66406641
* Represents information about programming constructs like variables, classes, interfaces etc.
6641-
*
6642-
* Deprecated Use {@link DocumentSymbol} or {@link WorkspaceSymbol} instead if supported.
6643-
*
6644-
* This class is deprecated in the LSP specification. It is not annotated with Deprecated
6645-
* annotation because the {@link org.eclipse.lsp4j.services.TextDocumentService#documentSymbol(DocumentSymbolParams)}
6646-
* method requires it and causes deprecated warning in the code of all users of that API.
6642+
* <p>
6643+
* Deprecated in LSP: Use {@link DocumentSymbol} or {@link WorkspaceSymbol} instead if supported.
66476644
*/
66486645
@JsonRpcData
66496646
@JsonAdapter(SymbolInformationTypeAdapter.Factory)
6647+
@ProtocolDeprecated
66506648
class SymbolInformation {
66516649
/**
66526650
* The name of this symbol.
66536651
*/
66546652
@NonNull
6655-
@Deprecated
6653+
@ProtocolDeprecated
66566654
String name
66576655

66586656
/**
66596657
* The kind of this symbol.
66606658
*/
66616659
@NonNull
6662-
@Deprecated
6660+
@ProtocolDeprecated
66636661
SymbolKind kind
66646662

66656663
/**
66666664
* Tags for this symbol.
66676665
* <p>
66686666
* Since 3.16.0
66696667
*/
6670-
@Deprecated
6668+
@ProtocolDeprecated
66716669
List<SymbolTag> tags
66726670

66736671
/**
66746672
* Indicates if this symbol is deprecated.
66756673
* <p>
66766674
* Since 3.8.0
6677-
*
6678-
* @deprecated Use {@link #tags} instead if supported.
6675+
* <p>
6676+
* Deprecated in LSP: Use {@link #tags} instead if supported.
66796677
*/
6680-
@Deprecated
6678+
@ProtocolDeprecated
66816679
Boolean deprecated
66826680

66836681
/**
@@ -6692,7 +6690,7 @@ class SymbolInformation {
66926690
* the symbols.
66936691
*/
66946692
@NonNull
6695-
@Deprecated
6693+
@ProtocolDeprecated
66966694
Location location
66976695

66986696
/**
@@ -6701,21 +6699,21 @@ class SymbolInformation {
67016699
* if necessary). It can't be used to re-infer a hierarchy for the document
67026700
* symbols.
67036701
*/
6704-
@Deprecated
6702+
@ProtocolDeprecated
67056703
String containerName
67066704

6707-
@Deprecated
6705+
@ProtocolDeprecated
67086706
new() {
67096707
}
67106708

6711-
@Deprecated
6709+
@ProtocolDeprecated
67126710
new(@NonNull String name, @NonNull SymbolKind kind, @NonNull Location location) {
67136711
this.name = Preconditions.checkNotNull(name, 'name')
67146712
this.kind = Preconditions.checkNotNull(kind, 'kind')
67156713
this.location = Preconditions.checkNotNull(location, 'location')
67166714
}
67176715

6718-
@Deprecated
6716+
@ProtocolDeprecated
67196717
new(@NonNull String name, @NonNull SymbolKind kind, @NonNull Location location, String containerName) {
67206718
this(name, kind, location)
67216719
this.containerName = containerName
@@ -6821,10 +6819,10 @@ class TextDocumentContentChangeEvent {
68216819

68226820
/**
68236821
* The length of the range that got replaced.
6824-
*
6825-
* @deprecated Use {@link #range} instead.
6822+
* <p>
6823+
* Deprecated in LSP: Use {@link #range} instead.
68266824
*/
6827-
@Deprecated
6825+
@ProtocolDeprecated
68286826
Integer rangeLength
68296827

68306828
/**

‎org.eclipse.lsp4j/src/main/java/org/eclipse/lsp4j/services/LanguageServer.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import org.eclipse.lsp4j.InitializedParams;
1919
import org.eclipse.lsp4j.SetTraceParams;
2020
import org.eclipse.lsp4j.WorkDoneProgressCancelParams;
21+
import org.eclipse.lsp4j.jsonrpc.ProtocolDeprecated;
2122
import org.eclipse.lsp4j.jsonrpc.services.JsonDelegate;
2223
import org.eclipse.lsp4j.jsonrpc.services.JsonNotification;
2324
import org.eclipse.lsp4j.jsonrpc.services.JsonRequest;
@@ -62,9 +63,9 @@ default void initialized(InitializedParams params) {
6263
}
6364

6465
/**
65-
* @deprecated Use {@link #initialized(InitializedParams)} instead.
66+
* Deprecated in LSP: Use {@link #initialized(InitializedParams)} instead.
6667
*/
67-
@Deprecated
68+
@ProtocolDeprecated
6869
default void initialized() {
6970
}
7071

0 commit comments

Comments
 (0)