0
# Server Reflection Services
1

2
Protocol buffer service reflection enabling dynamic service discovery and debugging tools. Server reflection allows clients to discover available services and their method signatures at runtime.
3

4
## Capabilities
5

6
### ProtoReflectionServiceV1
7

8
Current implementation of the server reflection service using the v1 protocol.
9

10
```java { .api }
11
/**
12
 * Provides reflection service for Protobuf services using v1 protocol.
13
 * Enables clients to discover available services and method signatures.
14
 */
15
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/2222")
16
public final class ProtoReflectionServiceV1 {
17
  
18
  /**
19
   * Creates an instance of ProtoReflectionServiceV1
20
   * @return BindableService that can be added to a gRPC server
21
   */
22
  public static BindableService newInstance();
23
  
24
  // Note: serverReflectionInfo() is an internal implementation method
25
  // Users don't call this directly - it's automatically invoked by gRPC framework
26
}
27
```
28

29
**Usage Examples:**
30

31
```java
32
import io.grpc.Server;
33
import io.grpc.ServerBuilder;
34
import io.grpc.protobuf.services.ProtoReflectionServiceV1;
35

36
// Add reflection service to server
37
Server server = ServerBuilder.forPort(8080)
38
    .addService(ProtoReflectionServiceV1.newInstance())
39
    .addService(new MyBusinessService())
40
    .addService(new AnotherService())
41
    .build();
42

43
server.start();
44
```
45

46
### ProtoReflectionService (Deprecated)
47

48
Legacy implementation using the deprecated v1alpha protocol.
49

50
```java { .api }
51
/**
52
 * Provides reflection service for Protobuf services using deprecated v1alpha protocol.
53
 * @deprecated Use ProtoReflectionServiceV1 instead
54
 */
55
@Deprecated
56
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/2222")
57
public final class ProtoReflectionService {
58
  
59
  /**
60
   * Creates a new instance (deprecated, use ProtoReflectionServiceV1 instead)
61
   * @return BindableService that can be added to a gRPC server
62
   * @deprecated Use ProtoReflectionServiceV1.newInstance() instead
63
   */
64
  @Deprecated
65
  public static BindableService newInstance();
66
  
67
  /**
68
   * Binds the service
69
   * @return ServerServiceDefinition for the reflection service
70
   */
71
  public ServerServiceDefinition bindService();
72
}
73
```
74

75
## Client Usage with Reflection
76

77
Server reflection enables various debugging and development tools:
78

79
### Using grpcurl with Reflection
80

81
```bash
82
# List all services available on the server
83
grpcurl -plaintext localhost:8080 list
84

85
# Get details about a specific service
86
grpcurl -plaintext localhost:8080 describe com.example.UserService
87

88
# Get details about a specific method
89
grpcurl -plaintext localhost:8080 describe com.example.UserService.GetUser
90
```
91

92
### Programmatic Client Discovery
93

94
```java
95
import io.grpc.reflection.v1.ServerReflectionGrpc;
96
import io.grpc.reflection.v1.ServerReflectionRequest;
97
import io.grpc.reflection.v1.ServerReflectionResponse;
98

99
// Create reflection client
100
ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 8080)
101
    .usePlaintext()
102
    .build();
103

104
ServerReflectionGrpc.ServerReflectionStub reflectionStub = 
105
    ServerReflectionGrpc.newStub(channel);
106

107
// Stream observer to handle responses
108
StreamObserver<ServerReflectionResponse> responseObserver = 
109
    new StreamObserver<ServerReflectionResponse>() {
110
        @Override
111
        public void onNext(ServerReflectionResponse response) {
112
            // Handle reflection response
113
            if (response.hasListServicesResponse()) {
114
                response.getListServicesResponse().getServiceList()
115
                    .forEach(service -> 
116
                        System.out.println("Service: " + service.getName())
117
                    );
118
            }
119
        }
120
        
121
        @Override
122
        public void onError(Throwable t) {
123
            System.err.println("Reflection error: " + t.getMessage());
124
        }
125
        
126
        @Override
127
        public void onCompleted() {
128
            System.out.println("Reflection completed");
129
        }
130
    };
131

132
// Request stream to send reflection requests
133
StreamObserver<ServerReflectionRequest> requestObserver = 
134
    reflectionStub.serverReflectionInfo(responseObserver);
135

136
// List all services
137
ServerReflectionRequest listServicesRequest = ServerReflectionRequest.newBuilder()
138
    .setListServices("")
139
    .build();
140
    
141
requestObserver.onNext(listServicesRequest);
142
requestObserver.onCompleted();
143
```
144

145
## Integration with Development Tools
146

147
Server reflection enables integration with various gRPC development and debugging tools:
148

149
```java
150
import io.grpc.Server;
151
import io.grpc.ServerBuilder;
152
import io.grpc.protobuf.services.ProtoReflectionServiceV1;
153
import io.grpc.protobuf.services.HealthStatusManager;
154

155
public class DevelopmentServer {
156
    
157
    public static void main(String[] args) throws Exception {
158
        HealthStatusManager healthManager = new HealthStatusManager();
159
        
160
        // Development server with reflection and health checking
161
        Server server = ServerBuilder.forPort(8080)
162
            // Add reflection for development tools
163
            .addService(ProtoReflectionServiceV1.newInstance())
164
            
165
            // Add health checking for load balancer integration
166
            .addService(healthManager.getHealthService())
167
            
168
            // Add business services
169
            .addService(new UserService())
170
            .addService(new OrderService())
171
            .build();
172
        
173
        server.start();
174
        healthManager.setStatus("", ServingStatus.SERVING);
175
        
176
        System.out.println("Development server started on port 8080");
177
        System.out.println("Use grpcurl to explore services:");
178
        System.out.println("  grpcurl -plaintext localhost:8080 list");
179
        
180
        server.awaitTermination();
181
    }
182
}
183
```
184

185
## Security Considerations
186

187
Server reflection exposes service information and should be used carefully in production:
188

189
```java
190
// Only enable reflection in development/staging environments
191
String environment = System.getProperty("environment", "development");
192

193
ServerBuilder<?> serverBuilder = ServerBuilder.forPort(8080);
194

195
if ("development".equals(environment) || "staging".equals(environment)) {
196
    // Enable reflection for development tools
197
    serverBuilder.addService(ProtoReflectionServiceV1.newInstance());
198
    System.out.println("Server reflection enabled for " + environment);
199
} else {
200
    System.out.println("Server reflection disabled in production");
201
}
202

203
Server server = serverBuilder
204
    .addService(new ProductionService())
205
    .build();
206
```