0
# Event Source Mapping
1

2
Management of event source mappings that connect Lambda functions to event sources like Amazon DynamoDB, Amazon Kinesis, Amazon SQS, Amazon MQ, Amazon MSK, Apache Kafka, and Amazon DocumentDB.
3

4
## Capabilities
5

6
### Event Source Mapping Creation
7

8
Creates mapping between event source and Lambda function.
9

10
```java { .api }
11
/**
12
 * Creates event source mapping to connect Lambda function with event source
13
 * @param request Event source mapping configuration
14
 * @return CreateEventSourceMappingResult containing mapping details
15
 * @throws ResourceNotFoundException if function or event source doesn't exist
16
 * @throws InvalidParameterValueException if parameters are invalid
17
 * @throws ResourceConflictException if mapping already exists
18
 * @throws TooManyRequestsException if concurrent requests exceed limits
19
 */
20
CreateEventSourceMappingResult createEventSourceMapping(CreateEventSourceMappingRequest request);
21

22
public class CreateEventSourceMappingRequest {
23
    /** Event source ARN (required for most sources) */
24
    private String eventSourceArn;
25
    /** Function name, ARN, or qualified ARN (required) */
26
    private String functionName;
27
    /** Whether mapping is enabled (optional, default: true) */
28
    private Boolean enabled;
29
    /** Batch size for records (optional, varies by source) */
30
    private Integer batchSize;
31
    /** Maximum batching window in seconds (optional) */
32
    private Integer maximumBatchingWindowInSeconds;
33
    /** Parallelization factor for Kinesis/DynamoDB (optional, range: 1-10) */
34
    private Integer parallelizationFactor;
35
    /** Starting position for Kinesis/DynamoDB (optional) */
36
    private EventSourcePosition startingPosition;
37
    /** Starting position timestamp for AT_TIMESTAMP (optional) */
38
    private java.util.Date startingPositionTimestamp;
39
    /** Destination configuration for failures (optional) */
40
    private DestinationConfig destinationConfig;
41
    /** Maximum record age in seconds (optional) */
42
    private Integer maximumRecordAgeInSeconds;
43
    /** Whether to split batch on error (optional) */
44
    private Boolean bisectBatchOnFunctionError;
45
    /** Maximum retry attempts (optional) */
46
    private Integer maximumRetryAttempts;
47
    /** Tumbling window in seconds (optional) */
48
    private Integer tumblingWindowInSeconds;
49
    /** Topic names for Kafka/MSK (optional) */
50
    private List<String> topics;
51
    /** Queue configurations for SQS (optional) */
52
    private List<String> queues;
53
    /** Source access configurations (optional) */
54
    private List<SourceAccessConfiguration> sourceAccessConfigurations;
55
    /** Self-managed event source config (optional) */
56
    private SelfManagedEventSource selfManagedEventSource;
57
    /** Function response types (optional) */
58
    private List<String> functionResponseTypes;
59
    /** Amazon managed Kafka event source config (optional) */
60
    private AmazonManagedKafkaEventSourceConfig amazonManagedKafkaEventSourceConfig;
61
    /** Self-managed Kafka event source config (optional) */
62
    private SelfManagedKafkaEventSourceConfig selfManagedKafkaEventSourceConfig;
63
    /** Scaling configuration (optional) */
64
    private ScalingConfig scalingConfig;
65
    /** DocumentDB event source config (optional) */
66
    private DocumentDBEventSourceConfig documentDBEventSourceConfig;
67
    
68
    // Fluent setters
69
    public CreateEventSourceMappingRequest withEventSourceArn(String eventSourceArn) { ... }
70
    public CreateEventSourceMappingRequest withFunctionName(String functionName) { ... }
71
    // ... other fluent setters
72
}
73

74
public class CreateEventSourceMappingResult {
75
    /** Event source mapping UUID */
76
    private String uuid;
77
    /** Batch size */
78
    private Integer batchSize;
79
    /** Maximum batching window in seconds */
80
    private Integer maximumBatchingWindowInSeconds;
81
    /** Parallelization factor */
82
    private Integer parallelizationFactor;
83
    /** Event source ARN */
84
    private String eventSourceArn;
85
    /** Function ARN */
86
    private String functionArn;
87
    /** Last modified timestamp */
88
    private java.util.Date lastModified;
89
    /** Last processing result */
90
    private String lastProcessingResult;
91
    /** State of the mapping */
92
    private String state;
93
    /** State transition reason */
94
    private String stateTransitionReason;
95
    /** Destination configuration */
96
    private DestinationConfig destinationConfig;
97
    /** Topic names */
98
    private List<String> topics;
99
    /** Queue configurations */
100
    private List<String> queues;
101
    /** Source access configurations */
102
    private List<SourceAccessConfiguration> sourceAccessConfigurations;
103
    /** Self-managed event source config */
104
    private SelfManagedEventSource selfManagedEventSource;
105
    /** Maximum record age in seconds */
106
    private Integer maximumRecordAgeInSeconds;
107
    /** Whether to split batch on error */
108
    private Boolean bisectBatchOnFunctionError;
109
    /** Maximum retry attempts */
110
    private Integer maximumRetryAttempts;
111
    /** Tumbling window in seconds */
112
    private Integer tumblingWindowInSeconds;
113
    /** Function response types */
114
    private List<String> functionResponseTypes;
115
    // ... other fields
116
}
117
```
118

119
### Event Source Mapping Operations
120

121
```java { .api }
122
/**
123
 * Gets event source mapping details
124
 * @param request Mapping retrieval parameters
125
 * @return GetEventSourceMappingResult containing mapping configuration
126
 */
127
GetEventSourceMappingResult getEventSourceMapping(GetEventSourceMappingRequest request);
128

129
/**
130
 * Updates existing event source mapping
131
 * @param request Mapping update parameters
132
 * @return UpdateEventSourceMappingResult with updated configuration
133
 */
134
UpdateEventSourceMappingResult updateEventSourceMapping(UpdateEventSourceMappingRequest request);
135

136
/**
137
 * Deletes event source mapping
138
 * @param request Mapping deletion parameters
139
 * @return DeleteEventSourceMappingResult with final mapping state
140
 */
141
DeleteEventSourceMappingResult deleteEventSourceMapping(DeleteEventSourceMappingRequest request);
142

143
/**
144
 * Lists event source mappings with optional filtering
145
 * @param request Listing parameters
146
 * @return ListEventSourceMappingsResult containing mappings and pagination
147
 */
148
ListEventSourceMappingsResult listEventSourceMappings(ListEventSourceMappingsRequest request);
149

150
/**
151
 * Lists all event source mappings
152
 * @return ListEventSourceMappingsResult containing all mappings
153
 */
154
ListEventSourceMappingsResult listEventSourceMappings();
155
```
156

157
### Supporting Types
158

159
```java { .api }
160
/** Event source starting position */
161
public enum EventSourcePosition {
162
    TRIM_HORIZON,  // Start from oldest record
163
    LATEST,        // Start from newest record  
164
    AT_TIMESTAMP   // Start from specific timestamp
165
}
166

167
/** Source access configuration for authentication */
168
public class SourceAccessConfiguration {
169
    /** Configuration type */
170
    private SourceAccessType type;
171
    /** Configuration URI */
172
    private String uri;
173
    
174
    public SourceAccessConfiguration withType(SourceAccessType type) { ... }
175
    public SourceAccessConfiguration withUri(String uri) { ... }
176
}
177

178
public enum SourceAccessType {
179
    BASIC_AUTH,           // Basic authentication
180
    VPC_SUBNET,           // VPC subnet ID
181
    VPC_SECURITY_GROUP,   // VPC security group ID
182
    SASL_SCRAM_512_AUTH,  // SASL/SCRAM authentication
183
    SASL_SCRAM_256_AUTH,  // SASL/SCRAM authentication
184
    VIRTUAL_HOST,         // Virtual host
185
    CLIENT_CERTIFICATE_TLS_AUTH  // TLS client certificate
186
}
187

188
/** Destination configuration for failed records */
189
public class DestinationConfig {
190
    /** Success destination */
191
    private OnSuccess onSuccess;
192
    /** Failure destination */
193
    private OnFailure onFailure;
194
    
195
    public DestinationConfig withOnSuccess(OnSuccess onSuccess) { ... }
196
    public DestinationConfig withOnFailure(OnFailure onFailure) { ... }
197
}
198

199
public class OnFailure {
200
    /** Destination ARN (SQS queue or SNS topic) */
201
    private String destination;
202
    
203
    public OnFailure withDestination(String destination) { ... }
204
}
205

206
public class OnSuccess {
207
    /** Destination ARN */
208
    private String destination;
209
    
210
    public OnSuccess withDestination(String destination) { ... }
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
import com.amazonaws.services.lambda.*;
218
import com.amazonaws.services.lambda.model.*;
219

220
AWSLambda lambdaClient = AWSLambdaClientBuilder.defaultClient();
221

222
// Create DynamoDB event source mapping
223
CreateEventSourceMappingRequest dynamoRequest = new CreateEventSourceMappingRequest()
224
    .withEventSourceArn("arn:aws:dynamodb:us-east-1:123456789012:table/MyTable/stream/2024-01-01T00:00:00.000")
225
    .withFunctionName("my-dynamo-processor")
226
    .withStartingPosition(EventSourcePosition.TRIM_HORIZON)
227
    .withBatchSize(10)
228
    .withMaximumBatchingWindowInSeconds(5)
229
    .withParallelizationFactor(2)
230
    .withMaximumRecordAgeInSeconds(3600)
231
    .withBisectBatchOnFunctionError(true)
232
    .withMaximumRetryAttempts(3)
233
    .withDestinationConfig(new DestinationConfig()
234
        .withOnFailure(new OnFailure()
235
            .withDestination("arn:aws:sqs:us-east-1:123456789012:failed-records")));
236

237
CreateEventSourceMappingResult dynamoResult = lambdaClient.createEventSourceMapping(dynamoRequest);
238
System.out.println("Created DynamoDB mapping: " + dynamoResult.getUuid());
239

240
// Create SQS event source mapping
241
CreateEventSourceMappingRequest sqsRequest = new CreateEventSourceMappingRequest()
242
    .withEventSourceArn("arn:aws:sqs:us-east-1:123456789012:my-queue")
243
    .withFunctionName("my-sqs-processor")
244
    .withBatchSize(5)
245
    .withMaximumBatchingWindowInSeconds(10);
246

247
CreateEventSourceMappingResult sqsResult = lambdaClient.createEventSourceMapping(sqsRequest);
248

249
// Create MSK (Kafka) event source mapping
250
CreateEventSourceMappingRequest mskRequest = new CreateEventSourceMappingRequest()
251
    .withEventSourceArn("arn:aws:kafka:us-east-1:123456789012:cluster/my-cluster/uuid")
252
    .withFunctionName("my-kafka-processor")
253
    .withTopics(Arrays.asList("orders", "payments"))
254
    .withBatchSize(100)
255
    .withStartingPosition(EventSourcePosition.LATEST)
256
    .withSourceAccessConfigurations(Arrays.asList(
257
        new SourceAccessConfiguration()
258
            .withType(SourceAccessType.VPC_SUBNET)
259
            .withUri("subnet-12345678"),
260
        new SourceAccessConfiguration()
261
            .withType(SourceAccessType.VPC_SECURITY_GROUP)
262
            .withUri("sg-87654321")
263
    ));
264

265
CreateEventSourceMappingResult mskResult = lambdaClient.createEventSourceMapping(mskRequest);
266

267
// Update event source mapping
268
UpdateEventSourceMappingRequest updateRequest = new UpdateEventSourceMappingRequest()
269
    .withUuid(dynamoResult.getUuid())
270
    .withBatchSize(20)
271
    .withMaximumBatchingWindowInSeconds(10)
272
    .withEnabled(true);
273

274
UpdateEventSourceMappingResult updateResult = lambdaClient.updateEventSourceMapping(updateRequest);
275

276
// List event source mappings for function
277
ListEventSourceMappingsRequest listRequest = new ListEventSourceMappingsRequest()
278
    .withFunctionName("my-dynamo-processor");
279

280
ListEventSourceMappingsResult listResult = lambdaClient.listEventSourceMappings(listRequest);
281
for (EventSourceMappingConfiguration mapping : listResult.getEventSourceMappings()) {
282
    System.out.println("Mapping: " + mapping.getUuid() + 
283
                      " - State: " + mapping.getState() +
284
                      " - Source: " + mapping.getEventSourceArn());
285
}
286

287
// Get specific mapping details
288
GetEventSourceMappingRequest getRequest = new GetEventSourceMappingRequest()
289
    .withUuid(dynamoResult.getUuid());
290

291
GetEventSourceMappingResult getResult = lambdaClient.getEventSourceMapping(getRequest);
292
System.out.println("Mapping state: " + getResult.getState());
293
System.out.println("Last processing result: " + getResult.getLastProcessingResult());
294

295
// Delete event source mapping
296
DeleteEventSourceMappingRequest deleteRequest = new DeleteEventSourceMappingRequest()
297
    .withUuid(dynamoResult.getUuid());
298

299
DeleteEventSourceMappingResult deleteResult = lambdaClient.deleteEventSourceMapping(deleteRequest);
300
System.out.println("Deleted mapping, final state: " + deleteResult.getState());
301
```