0
# Connection Management
1

2
Core connection lifecycle management, driver discovery, and connection establishment with authentication support for Apache PLC4X Java API.
3

4
## Capabilities
5

6
### PlcDriverManager
7

8
Factory interface for discovering and creating PLC drivers and connections.
9

10
```java { .api }
11
/**
12
 * Main factory interface for PLC driver management and connection creation
13
 */
14
public interface PlcDriverManager {
15
    /**
16
     * Get the default driver manager instance
17
     * @return Default PlcDriverManager implementation
18
     */
19
    static PlcDriverManager getDefault();
20
    
21
    /**
22
     * Get all registered protocol codes
23
     * @return Set of available protocol codes
24
     */
25
    Set<String> getProtocolCodes();
26
    
27
    /**
28
     * Get a specific driver by protocol code
29
     * @param protocolCode Protocol identifier (e.g., "modbus-tcp", "s7")
30
     * @return PlcDriver instance
31
     * @throws PlcConnectionException If protocol is not supported or driver cannot be created
32
     */
33
    PlcDriver getDriver(String protocolCode) throws PlcConnectionException;
34
    
35
    /**
36
     * Get driver for a specific connection URL
37
     * @param url Connection URL
38
     * @return PlcDriver instance
39
     * @throws PlcConnectionException If protocol is not supported or driver cannot be created
40
     */
41
    PlcDriver getDriverForUrl(String url) throws PlcConnectionException;
42
    
43
    /**
44
     * Get the connection manager interface
45
     * @return PlcConnectionManager instance
46
     */
47
    PlcConnectionManager getConnectionManager();
48
}
49
```
50

51
### DefaultPlcDriverManager
52

53
Default implementation of PlcDriverManager and PlcConnectionManager.
54

55
```java { .api }
56
/**
57
 * Default implementation providing driver discovery and connection creation
58
 */
59
public class DefaultPlcDriverManager implements PlcDriverManager, PlcConnectionManager {
60
    /**
61
     * Create driver manager using current context classloader
62
     */
63
    public DefaultPlcDriverManager();
64
    
65
    /**
66
     * Create driver manager with custom classloader for driver discovery
67
     * @param classLoader Classloader for driver discovery
68
     */
69
    public DefaultPlcDriverManager(ClassLoader classLoader);
70
}
71
```
72

73
### PlcConnectionManager
74

75
Simplified interface for connection management.
76

77
```java { .api }
78
/**
79
 * Interface for connection management providing methods to create and manage PLC connections
80
 */
81
public interface PlcConnectionManager {
82
    /**
83
     * Create a connection from a connection URL
84
     * @param url Connection URL (e.g., "modbus-tcp://192.168.1.100:502")
85
     * @return PlcConnection instance
86
     * @throws PlcConnectionException If connection cannot be established
87
     */
88
    PlcConnection getConnection(String url) throws PlcConnectionException;
89
    
90
    /**
91
     * Create an authenticated connection from a connection URL
92
     * @param url Connection URL
93
     * @param authentication Authentication credentials
94
     * @return PlcConnection instance
95
     * @throws PlcConnectionException If connection cannot be established
96
     */
97
    PlcConnection getConnection(String url, PlcAuthentication authentication) throws PlcConnectionException;
98
}
99
```
100

101
### PlcConnection
102

103
Main connection interface for PLC communication.
104

105
```java { .api }
106
/**
107
 * Main connection interface extending AutoCloseable for resource management
108
 */
109
public interface PlcConnection extends AutoCloseable {
110
    /**
111
     * Establish the connection to the PLC
112
     * @throws PlcConnectionException If connection fails
113
     */
114
    void connect() throws PlcConnectionException;
115
    
116
    /**
117
     * Check if connection is currently active
118
     * @return true if connected, false otherwise
119
     */
120
    boolean isConnected();
121
    
122
    /**
123
     * Close the connection and release resources
124
     * @throws Exception If closing fails
125
     */
126
    void close() throws Exception;
127
    
128
    /**
129
     * Parse a tag address string into a PlcTag object
130
     * @param tagAddress String representation of tag address
131
     * @return Optional PlcTag if parsing succeeds
132
     */
133
    Optional<PlcTag> parseTagAddress(String tagAddress);
134
    
135
    /**
136
     * Parse values for a specific tag
137
     * @param tag The PlcTag to parse values for
138
     * @param values Raw values to parse
139
     * @return Optional PlcValue if parsing succeeds
140
     */
141
    Optional<PlcValue> parseTagValue(PlcTag tag, Object... values);
142
    
143
    /**
144
     * Get connection metadata including supported capabilities
145
     * @return PlcConnectionMetadata with capability information
146
     */
147
    PlcConnectionMetadata getMetadata();
148
    
149
    /**
150
     * Ping the PLC connection
151
     * @return CompletableFuture with ping response
152
     */
153
    CompletableFuture<? extends PlcPingResponse> ping();
154
    
155
    /**
156
     * Create a read request builder
157
     * @return PlcReadRequest.Builder instance
158
     */
159
    PlcReadRequest.Builder readRequestBuilder();
160
    
161
    /**
162
     * Create a write request builder
163
     * @return PlcWriteRequest.Builder instance
164
     */
165
    PlcWriteRequest.Builder writeRequestBuilder();
166
    
167
    /**
168
     * Create a subscription request builder
169
     * @return PlcSubscriptionRequest.Builder instance
170
     */
171
    PlcSubscriptionRequest.Builder subscriptionRequestBuilder();
172
    
173
    /**
174
     * Create an unsubscription request builder
175
     * @return PlcUnsubscriptionRequest.Builder instance
176
     */
177
    PlcUnsubscriptionRequest.Builder unsubscriptionRequestBuilder();
178
    
179
    /**
180
     * Create a browse request builder
181
     * @return PlcBrowseRequest.Builder instance
182
     */
183
    PlcBrowseRequest.Builder browseRequestBuilder();
184
}
185
```
186

187
### EventPlcConnection
188

189
Extended connection interface with event listener support.
190

191
```java { .api }
192
/**
193
 * Extended connection interface for event-driven communication
194
 */
195
public interface EventPlcConnection extends PlcConnection {
196
    /**
197
     * Add an event listener for connection events
198
     * @param listener EventListener implementation
199
     */
200
    void addEventListener(EventListener listener);
201
    
202
    /**
203
     * Remove an event listener
204
     * @param listener EventListener to remove
205
     */
206
    void removeEventListener(EventListener listener);
207
}
208
```
209

210
### PlcDriver
211

212
Protocol-specific driver interface.
213

214
```java { .api }
215
/**
216
 * Protocol-specific driver interface
217
 */
218
public interface PlcDriver {
219
    /**
220
     * Get the protocol short code
221
     * @return Protocol identifier (e.g., "modbus-tcp", "s7")
222
     */
223
    String getProtocolCode();
224
    
225
    /**
226
     * Get the full protocol name
227
     * @return Human-readable protocol name
228
     */
229
    String getProtocolName();
230
    
231
    /**
232
     * Get driver metadata including capabilities
233
     * @return PlcDriverMetadata with driver information
234
     */
235
    PlcDriverMetadata getMetadata();
236
    
237
    /**
238
     * Create a connection using this driver
239
     * @param url Connection URL
240
     * @return PlcConnection instance
241
     * @throws PlcConnectionException If connection cannot be established
242
     */
243
    PlcConnection getConnection(String url) throws PlcConnectionException;
244
    
245
    /**
246
     * Create an authenticated connection using this driver
247
     * @param url Connection URL
248
     * @param authentication Authentication credentials
249
     * @return PlcConnection instance
250
     * @throws PlcConnectionException If connection cannot be established
251
     */
252
    PlcConnection getConnection(String url, PlcAuthentication authentication) throws PlcConnectionException;
253
    
254
    /**
255
     * Prepare a tag from an address string
256
     * @param tagAddress Tag address string
257
     * @return PlcTag instance
258
     * @throws PlcInvalidTagException If tag address is invalid
259
     */
260
    PlcTag prepareTag(String tagAddress) throws PlcInvalidTagException;
261
    
262
    /**
263
     * Create a discovery request builder for this driver
264
     * @return PlcDiscoveryRequest.Builder instance
265
     */
266
    PlcDiscoveryRequest.Builder discoveryRequestBuilder();
267
}
268
```
269

270
**Usage Examples:**
271

272
```java
273
import org.apache.plc4x.java.DefaultPlcDriverManager;
274
import org.apache.plc4x.java.api.PlcConnection;
275
import org.apache.plc4x.java.api.PlcConnectionManager;
276
import org.apache.plc4x.java.api.PlcDriverManager;
277
import org.apache.plc4x.java.api.authentication.PlcUsernamePasswordAuthentication;
278

279
// Basic connection
280
PlcDriverManager driverManager = new DefaultPlcDriverManager();
281
PlcConnectionManager connectionManager = driverManager.getConnectionManager();
282
try (PlcConnection connection = connectionManager.getConnection("modbus-tcp://192.168.1.100:502")) {
283
    connection.connect();
284
    System.out.println("Connected: " + connection.isConnected());
285
    
286
    // Use connection for operations...
287
    
288
} // Auto-close when done
289

290
// Authenticated connection
291
PlcUsernamePasswordAuthentication auth = new PlcUsernamePasswordAuthentication("admin", "password");
292
try (PlcConnection connection = connectionManager.getConnection("s7://192.168.1.200/0/1", auth)) {
293
    connection.connect();
294
    
295
    // Check capabilities
296
    if (connection.getMetadata().isReadSupported()) {
297
        // Perform read operations
298
    }
299
}
300

301
// Driver discovery
302
Set<String> protocols = driverManager.getProtocolCodes();
303
System.out.println("Available protocols: " + protocols);
304

305
PlcDriver modbusDriver = driverManager.getDriver("modbus-tcp");
306
System.out.println("Driver: " + modbusDriver.getProtocolName());
307
```
308

309
## Types
310

311
### Ping Operations
312

313
```java { .api }
314
public interface PlcPingRequest extends PlcRequest {
315
    CompletableFuture<? extends PlcPingResponse> execute();
316
}
317

318
public interface PlcPingResponse extends PlcResponse {
319
    PlcRequest getRequest();
320
}
321
```
322

323
### Metadata Types
324

325
```java { .api }
326
public interface PlcConnectionMetadata {
327
    boolean isReadSupported();
328
    boolean isWriteSupported();
329
    boolean isSubscribeSupported();
330
    boolean isBrowseSupported();
331
}
332

333
public interface PlcDriverMetadata {
334
    Optional<String> getDefaultTransportCode();
335
    List<String> getSupportedTransportCodes();
336
    Optional<OptionMetadata> getProtocolConfigurationOptionMetadata();
337
    Optional<OptionMetadata> getTransportConfigurationOptionMetadata(String transportCode);
338
    boolean isDiscoverySupported();
339
}
340
```
341

342
### Model Types
343

344
```java { .api }
345
public interface PlcTag {
346
    String getAddressString();
347
    PlcValueType getPlcValueType();
348
    List<ArrayInfo> getArrayInfo();
349
}
350

351
public interface ArrayInfo {
352
    int getSize();
353
    int getLowerBound(); 
354
    int getUpperBound();
355
}
356
```