0
# Apache PLC4X Java API
1

2
Apache PLC4X Java API provides a unified, protocol-agnostic interface for communicating with industrial programmable logic controllers (PLCs). It abstracts the complexity of industrial communication protocols, enabling developers to build applications that can communicate with various PLC systems using a consistent programming interface.
3

4
## Package Information
5

6
- **Package Name**: org.apache.plc4x:plc4j-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.plc4x</groupId>
13
    <artifactId>plc4j-api</artifactId>
14
    <version>0.13.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.plc4x.java.DefaultPlcDriverManager;
22
import org.apache.plc4x.java.api.PlcConnection;
23
import org.apache.plc4x.java.api.PlcDriverManager;
24
import org.apache.plc4x.java.api.PlcConnectionManager;
25
import org.apache.plc4x.java.api.messages.*;
26
import org.apache.plc4x.java.api.value.PlcValue;
27
import org.apache.plc4x.java.api.types.PlcResponseCode;
28
```
29

30
## Basic Usage
31

32
```java
33
import org.apache.plc4x.java.DefaultPlcDriverManager;
34
import org.apache.plc4x.java.api.PlcConnection;
35
import org.apache.plc4x.java.api.messages.PlcReadRequest;
36
import org.apache.plc4x.java.api.messages.PlcReadResponse;
37

38
// Create connection manager
39
PlcDriverManager driverManager = new DefaultPlcDriverManager();
40
PlcConnectionManager connectionManager = driverManager.getConnectionManager();
41

42
// Connect to PLC
43
try (PlcConnection connection = connectionManager.getConnection("modbus-tcp://192.168.1.100:502")) {
44
    connection.connect();
45
    
46
    // Create and execute read request
47
    PlcReadRequest readRequest = connection.readRequestBuilder()
48
        .addTagAddress("sensor1", "holding-register:1")
49
        .addTagAddress("sensor2", "holding-register:2") 
50
        .build();
51
        
52
    PlcReadResponse response = readRequest.execute().get();
53
    
54
    // Extract values
55
    if (response.getResponseCode("sensor1") == PlcResponseCode.OK) {
56
        int value1 = response.getInteger("sensor1");
57
        int value2 = response.getInteger("sensor2");
58
        System.out.println("Sensor1: " + value1 + ", Sensor2: " + value2);
59
    }
60
}
61
```
62

63
## Architecture
64

65
Apache PLC4X Java API is built around several key components:
66

67
- **Driver Management**: `PlcDriverManager` provides discovery and factory methods for protocol-specific drivers
68
- **Connection Layer**: `PlcConnection` abstracts PLC connections with lifecycle management and capability detection
69
- **Message System**: Type-safe request/response pattern with builders for all operations (read, write, subscribe, browse)
70
- **Value System**: `PlcValue` provides universal value abstraction with automatic type conversion
71
- **Asynchronous Operations**: All operations return `CompletableFuture` for non-blocking execution
72
- **Metadata System**: Capability discovery and configuration options through driver and connection metadata
73

74
## Capabilities
75

76
### Connection Management
77

78
Core connection lifecycle management, driver discovery, and connection establishment with authentication support.
79

80
```java { .api }
81
public interface PlcDriverManager {
82
    static PlcDriverManager getDefault();
83
    Set<String> getProtocolCodes();
84
    PlcDriver getDriver(String protocolCode) throws PlcConnectionException;
85
    PlcDriver getDriverForUrl(String url) throws PlcConnectionException;
86
    PlcConnectionManager getConnectionManager();
87
}
88

89
public interface PlcConnectionManager {
90
    PlcConnection getConnection(String url) throws PlcConnectionException;
91
    PlcConnection getConnection(String url, PlcAuthentication authentication) throws PlcConnectionException;
92
}
93

94
public interface PlcConnection extends AutoCloseable {
95
    void connect() throws PlcConnectionException;
96
    boolean isConnected();
97
    void close() throws Exception;
98
    PlcConnectionMetadata getMetadata();
99
    CompletableFuture<? extends PlcPingResponse> ping();
100
}
101
```
102

103
[Connection Management](./connection-management.md)
104

105
### Read Operations
106

107
Type-safe data reading from PLC tags with comprehensive value conversion and validation.
108

109
```java { .api }
110
public interface PlcReadRequest extends PlcTagRequest {
111
    CompletableFuture<? extends PlcReadResponse> execute();
112
    
113
    interface Builder extends PlcRequestBuilder {
114
        Builder addTagAddress(String name, String tagAddress);
115
        Builder addTag(String name, PlcTag tag);
116
        PlcReadRequest build();
117
    }
118
}
119

120
public interface PlcReadResponse extends PlcTagResponse {
121
    PlcValue getPlcValue(String name);
122
    int getInteger(String name);
123
    boolean getBoolean(String name);
124
    String getString(String name);
125
    // Additional type-specific getters...
126
}
127
```
128

129
[Read Operations](./read-operations.md)
130

131
### Write Operations
132

133
Type-safe data writing to PLC tags with value validation and conversion.
134

135
```java { .api }
136
public interface PlcWriteRequest extends PlcTagRequest {
137
    CompletableFuture<? extends PlcWriteResponse> execute();
138
    
139
    interface Builder extends PlcRequestBuilder {
140
        Builder addTagAddress(String name, String tagAddress, Object... values);
141
        Builder addTag(String name, PlcTag tag, Object... values);
142
        PlcWriteRequest build();
143
    }
144
}
145
```
146

147
[Write Operations](./write-operations.md)
148

149
### Subscription System
150

151
Event-driven communication with multiple subscription types for real-time data monitoring.
152

153
```java { .api }
154
public interface PlcSubscriptionRequest extends PlcSubscriptionTagRequest {
155
    CompletableFuture<? extends PlcSubscriptionResponse> execute();
156
    
157
    interface Builder extends PlcRequestBuilder {
158
        Builder setConsumer(Consumer<PlcSubscriptionEvent> consumer);
159
        Builder addCyclicTagAddress(String name, String tagAddress, Duration duration);
160
        Builder addChangeOfStateTagAddress(String name, String tagAddress);
161
        Builder addEventTagAddress(String name, String tagAddress);
162
        PlcSubscriptionRequest build();
163
    }
164
}
165

166
public interface PlcSubscriptionEvent extends PlcReadResponse {
167
    Instant getTimestamp();
168
}
169
```
170

171
[Subscription System](./subscription-system.md)
172

173
### Value System
174

175
Universal value abstraction providing type-safe access to PLC data with automatic conversion.
176

177
```java { .api }
178
public interface PlcValue {
179
    PlcValueType getPlcValueType();
180
    Object getObject();
181
    boolean isBoolean();
182
    boolean getBoolean();
183
    int getInteger();
184
    String getString();
185
    // Comprehensive type system...
186
}
187
```
188

189
[Value System](./value-system.md)
190

191
### Browse Operations
192

193
PLC namespace exploration and tag discovery capabilities.
194

195
```java { .api }
196
public interface PlcBrowseRequest extends PlcRequest {
197
    CompletableFuture<? extends PlcBrowseResponse> execute();
198
    
199
    interface Builder extends PlcRequestBuilder {
200
        Builder addQuery(String name, String query);
201
        PlcBrowseRequest build();
202
    }
203
}
204
```
205

206
[Browse Operations](./browse-operations.md)
207

208
### Exception Handling
209

210
Comprehensive exception hierarchy for robust error handling in industrial communication.
211

212
```java { .api }
213
public class PlcException extends Exception { }
214
public class PlcConnectionException extends PlcException { }
215
public class PlcIoException extends PlcException { }
216
public class PlcProtocolException extends PlcException { }
217
// Additional specific exceptions...
218
```
219

220
[Exception Handling](./exception-handling.md)
221

222
## Types
223

224
### Core Enums
225

226
```java { .api }
227
public enum PlcResponseCode {
228
    OK, NOT_FOUND, ACCESS_DENIED, INVALID_ADDRESS, INVALID_DATATYPE,
229
    INVALID_DATA, INTERNAL_ERROR, REMOTE_BUSY, REMOTE_ERROR, 
230
    UNSUPPORTED, RESPONSE_PENDING;
231
    
232
    short getValue();
233
    static PlcResponseCode enumForValue(short value);
234
}
235

236
public enum PlcValueType {
237
    NULL, BOOL, BYTE, WORD, DWORD, LWORD,
238
    USINT, UINT, UDINT, ULINT, SINT, INT, DINT, LINT,
239
    REAL, LREAL, CHAR, WCHAR, STRING, WSTRING,
240
    TIME, LTIME, DATE, LDATE, TIME_OF_DAY, LTIME_OF_DAY,
241
    DATE_AND_TIME, DATE_AND_LTIME, LDATE_AND_TIME,
242
    Struct, List, RAW_BYTE_ARRAY;
243
    
244
    short getValue();
245
    Class<?> getDefaultJavaType();
246
}
247

248
public enum PlcSubscriptionType {
249
    CYCLIC, CHANGE_OF_STATE, EVENT
250
}
251
```
252

253
### Authentication Types
254

255
```java { .api }
256
public interface PlcAuthentication { }
257

258
public class PlcUsernamePasswordAuthentication implements PlcAuthentication {
259
    public PlcUsernamePasswordAuthentication(String username, String password);
260
    public String getUsername();
261
    public String getPassword();
262
}
263
```
264

265
### Metadata Types
266

267
```java { .api }
268
public interface PlcConnectionMetadata {
269
    boolean isReadSupported();
270
    boolean isWriteSupported();
271
    boolean isSubscribeSupported();
272
    boolean isBrowseSupported();
273
}
274

275
public interface PlcDriverMetadata {
276
    Optional<String> getDefaultTransportCode();
277
    List<String> getSupportedTransportCodes();
278
    boolean isDiscoverySupported();
279
}
280
```