0
# Socket Addresses
1

2
The gRPC In-Process Transport provides two types of socket addresses for identifying servers: named addresses using `InProcessSocketAddress` and anonymous addresses using `AnonymousInProcessSocketAddress`. These addresses enable different patterns for server identification and client connection.
3

4
## Capabilities
5

6
### InProcessSocketAddress
7

8
A socket address that identifies an in-process server by name. Multiple clients can connect to the same named server.
9

10
```java { .api }
11
/**
12
 * Custom SocketAddress class for InProcessTransport.
13
 */
14
public final class InProcessSocketAddress extends SocketAddress {
15
    /**
16
     * Construct an address for a server identified by name.
17
     * @param name The name of the inprocess server
18
     */
19
    public InProcessSocketAddress(String name);
20
    
21
    /**
22
     * Gets the name of the inprocess server.
23
     * @return the server name
24
     */
25
    public String getName();
26
    
27
    /**
28
     * Returns the server name.
29
     * @return the server name
30
     */
31
    public String toString();
32
    
33
    /**
34
     * Hash code based on server name.
35
     * @return hash code
36
     */
37
    public int hashCode();
38
    
39
    /**
40
     * Returns true if the object is of the same type and server names match.
41
     * @param obj the object to compare
42
     * @return true if equal
43
     */
44
    public boolean equals(Object obj);
45
}
46
```
47

48
**Usage Examples:**
49

50
```java
51
// Create named address
52
InProcessSocketAddress address = new InProcessSocketAddress("user-service");
53

54
// Get server name
55
String serverName = address.getName(); // Returns "user-service"
56

57
// Use with builders
58
InProcessServerBuilder serverBuilder = 
59
    InProcessServerBuilder.forAddress(address);
60
InProcessChannelBuilder channelBuilder = 
61
    InProcessChannelBuilder.forAddress(address);
62

63
// Addresses with same name are equal
64
InProcessSocketAddress addr1 = new InProcessSocketAddress("service");
65
InProcessSocketAddress addr2 = new InProcessSocketAddress("service");
66
boolean isEqual = addr1.equals(addr2); // Returns true
67
```
68

69
### AnonymousInProcessSocketAddress
70

71
A socket address for anonymous in-process servers that can only be referenced via the specific address instance. This provides better isolation than named servers.
72

73
```java { .api }
74
/**
75
 * Custom SocketAddress class for InProcessTransport, for a server which 
76
 * can only be referenced via this address instance.
77
 */
78
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/8626")
79
public final class AnonymousInProcessSocketAddress extends SocketAddress {
80
    /**
81
     * Creates a new AnonymousInProcessSocketAddress.
82
     */
83
    public AnonymousInProcessSocketAddress();
84
}
85
```
86

87
**Usage Examples:**
88

89
```java
90
// Create anonymous address
91
AnonymousInProcessSocketAddress address = new AnonymousInProcessSocketAddress();
92

93
// Create server with anonymous address
94
Server server = InProcessServerBuilder.forAddress(address)
95
    .addService(new MyServiceImpl())
96
    .build()
97
    .start();
98

99
// Create channel using the same address instance
100
Channel channel = InProcessChannelBuilder.forAddress(address)
101
    .build();
102

103
// Only this specific address instance can connect to the server
104
// Creating a new AnonymousInProcessSocketAddress() will NOT connect to the same server
105
```
106

107
## Address Types Comparison
108

109
| Feature | InProcessSocketAddress | AnonymousInProcessSocketAddress |
110
|---------|----------------------|--------------------------------|
111
| Identification | Named (string-based) | Instance-based |
112
| Multiple Clients | ✅ Yes | ✅ Yes |
113
| Server Discovery | By name lookup | By address instance reference |
114
| Isolation | Shared namespace | Complete isolation |
115
| Use Case | General purpose, testing with known names | Maximum isolation, advanced testing scenarios |
116
| Status | Stable | Experimental |
117
118
## Usage Patterns
119

120
### Named Server Pattern
121

122
Use `InProcessSocketAddress` when you need multiple clients to connect to the same server or when you want to use human-readable server names.
123

124
```java
125
String serviceName = "order-service";
126
InProcessSocketAddress address = new InProcessSocketAddress(serviceName);
127

128
// Server setup
129
Server server = InProcessServerBuilder.forAddress(address)
130
    .addService(new OrderServiceImpl())
131
    .build()
132
    .start();
133

134
// Multiple clients can connect using the same name
135
Channel channel1 = InProcessChannelBuilder.forAddress(address).build();
136
Channel channel2 = InProcessChannelBuilder.forName(serviceName).build(); // Equivalent
137
```
138

139
### Anonymous Server Pattern
140

141
Use `AnonymousInProcessSocketAddress` when you need complete isolation and want to ensure only specific code can access the server.
142

143
```java
144
// Create anonymous address
145
AnonymousInProcessSocketAddress address = new AnonymousInProcessSocketAddress();
146

147
// Server setup - only accessible via this address instance
148
Server server = InProcessServerBuilder.forAddress(address)
149
    .addService(new SecureServiceImpl())
150
    .build()
151
    .start();
152

153
// Only this specific address can connect
154
Channel channel = InProcessChannelBuilder.forAddress(address).build();
155

156
// This would create a DIFFERENT anonymous server (not connected)
157
// AnonymousInProcessSocketAddress differentAddress = new AnonymousInProcessSocketAddress();
158
```
159

160
### Testing Isolation
161

162
Anonymous addresses provide better test isolation:
163

164
```java
165
@Test
166
void testServiceA() {
167
    AnonymousInProcessSocketAddress address = new AnonymousInProcessSocketAddress();
168
    // This test's server is completely isolated
169
    Server server = InProcessServerBuilder.forAddress(address)
170
        .addService(new ServiceAImpl())
171
        .build()
172
        .start();
173
    
174
    Channel channel = InProcessChannelBuilder.forAddress(address).build();
175
    // Test implementation...
176
}
177

178
@Test
179
void testServiceB() {
180
    AnonymousInProcessSocketAddress address = new AnonymousInProcessSocketAddress();
181
    // This test's server is also completely isolated
182
    Server server = InProcessServerBuilder.forAddress(address)
183
        .addService(new ServiceBImpl())
184
        .build()
185
        .start();
186
    
187
    Channel channel = InProcessChannelBuilder.forAddress(address).build();
188
    // Test implementation...
189
}
190
```
191

192
## Error Handling
193

194
### InProcessSocketAddress
195

196
- `NullPointerException` - Thrown if name parameter is null in constructor
197
- Name conflicts are handled at the server level during registration
198

199
### AnonymousInProcessSocketAddress
200

201
- `IOException` - Can be thrown during server registration if address is already in use
202
- Thread-safe for concurrent access to the same address instance
203

204
## Thread Safety
205

206
Both address types are **thread-safe**:
207

208
- `InProcessSocketAddress` - All methods are thread-safe. Multiple threads can safely access the same address instance concurrently.
209
- `AnonymousInProcessSocketAddress` - Internally synchronized for thread-safe server registration and access. Safe for concurrent use across multiple threads.
210

211
## Performance Considerations
212

213
- `InProcessSocketAddress` uses string-based lookups in a concurrent map
214
- `AnonymousInProcessSocketAddress` uses direct object references for faster access
215
- Both address types have minimal memory overhead
216
- Address equality checks are optimized for performance