0
# Advanced Features
1

2
Collaboration, messages, login components, and frontend integration.
3

4
**Quick links:** [Collaboration Engine](#collaboration-engine) | [Messages](#messages) | [Event Handling](#event-handling) | [Functional Interfaces](#common-functional-interfaces)
5

6
## Collaboration Engine
7

8
Real-time collaboration capabilities for multi-user applications with presence awareness.
9

10
```java { .api }
11
/**
12
 * Main entry point for collaboration features
13
 * Provides real-time synchronization across multiple users
14
 */
15
class CollaborationEngine {
16
    /**
17
     * Gets the collaboration engine instance
18
     * @return CollaborationEngine instance
19
     */
20
    static CollaborationEngine getInstance();
21

22
    /**
23
     * Configures the collaboration engine
24
     * @param service - Vaadin service
25
     * @param configuration - Engine configuration
26
     */
27
    static void configure(VaadinService service, CollaborationEngineConfiguration configuration);
28

29
    /**
30
     * Gets user info from request
31
     * @param request - Vaadin request
32
     * @return UserInfo instance
33
     */
34
    UserInfo getUserInfo(VaadinRequest request);
35

36
    /**
37
     * Creates a collaborative binder
38
     * @param session - Vaadin session
39
     * @param beanType - Bean class type
40
     * @return CollaborationBinder instance
41
     */
42
    CollaborationBinder createBinder(VaadinSession session, Class<?> beanType);
43
}
44

45
/**
46
 * Configuration for collaboration engine
47
 */
48
class CollaborationEngineConfiguration {
49
    /**
50
     * Sets whether to automatically activate push
51
     * @param automaticallyActivatePush - true to auto-activate
52
     */
53
    void setAutomaticallyActivatePush(boolean automaticallyActivatePush);
54

55
    /**
56
     * Sets the license key for production use
57
     * @param licenseKey - License key string
58
     */
59
    void setLicenseKey(String licenseKey);
60
}
61

62
/**
63
 * User information for collaboration
64
 */
65
class UserInfo {
66
    UserInfo(String userId);
67
    UserInfo(String userId, String name);
68
    UserInfo(String userId, String name, String image);
69
    String getId();
70
    String getName();
71
    String getImage();
72
    String getAbbreviation();
73
    String getColorIndex();
74
}
75

76
/**
77
 * Avatar group showing active collaborators
78
 */
79
class CollaborationAvatarGroup extends Component {
80
    /**
81
     * Creates collaborative avatar group
82
     * @param localUser - Local user info
83
     * @param topicId - Topic identifier
84
     */
85
    CollaborationAvatarGroup(UserInfo localUser, String topicId);
86

87
    /**
88
     * Creates with engine instance
89
     * @param localUser - Local user info
90
     * @param engine - Collaboration engine
91
     * @param topicId - Topic identifier
92
     */
93
    CollaborationAvatarGroup(UserInfo localUser, CollaborationEngine engine, String topicId);
94

95
    /**
96
     * Sets maximum avatars visible
97
     * @param maxItemsVisible - Maximum count
98
     */
99
    void setMaxItemsVisible(int maxItemsVisible);
100

101
    /**
102
     * Sets whether to show own user
103
     * @param ownUser - true to show own user
104
     */
105
    void setOwnUser(boolean ownUser);
106
}
107

108
/**
109
 * Collaborative form binder with real-time synchronization
110
 */
111
class CollaborationBinder extends Binder {
112
    /**
113
     * Creates collaborative binder
114
     * @param beanType - Bean class type
115
     * @param localUser - Local user info
116
     * @param topicId - Topic identifier
117
     */
118
    CollaborationBinder(Class<?> beanType, UserInfo localUser, String topicId);
119

120
    /**
121
     * Sets the collaboration topic
122
     * @param topicId - Topic identifier
123
     * @param defaultValue - Supplier for default value
124
     */
125
    void setTopic(String topicId, Supplier<?> defaultValue);
126

127
    /**
128
     * Adds value change listener for collaborative updates
129
     * @param listener - Value change listener
130
     * @return Registration for removing listener
131
     */
132
    Registration addValueChangeListener(ValueChangeListener listener);
133
}
134

135
/**
136
 * Collaborative list with real-time synchronization
137
 */
138
class CollaborationList<T> {
139
    /**
140
     * Creates collaborative list
141
     * @param engine - Collaboration engine
142
     * @param localUser - Local user info
143
     * @param topicId - Topic identifier
144
     * @param itemType - Item class type
145
     */
146
    CollaborationList(CollaborationEngine engine, UserInfo localUser, String topicId, Class<T> itemType);
147

148
    /**
149
     * Inserts item at index
150
     * @param index - Insert position
151
     * @param item - Item to insert
152
     */
153
    void insertItem(int index, T item);
154

155
    /**
156
     * Appends item to end
157
     * @param item - Item to append
158
     */
159
    void appendItem(T item);
160

161
    /**
162
     * Removes item at index
163
     * @param index - Item index
164
     */
165
    void removeItem(int index);
166

167
    /**
168
     * Updates item at index
169
     * @param index - Item index
170
     * @param item - Updated item
171
     */
172
    void setItem(int index, T item);
173

174
    /**
175
     * Gets item at index
176
     * @param index - Item index
177
     * @return Item at index
178
     */
179
    T getItem(int index);
180

181
    /**
182
     * Gets list size
183
     * @return Size of list
184
     */
185
    int getSize();
186

187
    /**
188
     * Subscribes to collaborative changes
189
     * @param subscriber - Change subscriber
190
     * @return Registration for removing subscription
191
     */
192
    Registration subscribe(CollaborationListSubscriber<T> subscriber);
193
}
194

195
/**
196
 * Subscriber for collaborative list changes
197
 */
198
interface CollaborationListSubscriber<T> {
199
    /**
200
     * Called when item is inserted
201
     * @param index - Insert position
202
     * @param item - Inserted item
203
     * @param user - User who inserted
204
     */
205
    void onItemInserted(int index, T item, UserInfo user);
206

207
    /**
208
     * Called when item is updated
209
     * @param index - Item index
210
     * @param item - Updated item
211
     * @param user - User who updated
212
     */
213
    void onItemUpdated(int index, T item, UserInfo user);
214

215
    /**
216
     * Called when item is removed
217
     * @param index - Item index
218
     * @param item - Removed item
219
     * @param user - User who removed
220
     */
221
    void onItemRemoved(int index, T item, UserInfo user);
222
}
223

224
/**
225
 * Collaborative message list for real-time chat
226
 */
227
class CollaborationMessageList {
228
    /**
229
     * Creates collaborative message list
230
     * @param localUser - Local user info
231
     * @param topicId - Topic identifier
232
     * @param messageList - MessageList component
233
     * @param messageInput - MessageInput component
234
     */
235
    CollaborationMessageList(UserInfo localUser, String topicId,
236
                             MessageList messageList, MessageInput messageInput);
237

238
    /**
239
     * Sets custom submit handler
240
     * @param submitter - Submit handler
241
     */
242
    void setSubmitter(BiConsumer<MessageInput, MessageListItem> submitter);
243
}
244
```
245

246
**License Note**: CollaborationEngine is free for development (up to 10 users) but requires a separate license for production use.
247

248
**Usage Examples:**
249

250
```java
251
// Collaborative avatar group
252
UserInfo localUser = new UserInfo("user-123", "John Doe", "/images/john.png");
253
CollaborationAvatarGroup avatarGroup = new CollaborationAvatarGroup(
254
    localUser, "document-456"
255
);
256
avatarGroup.setMaxItemsVisible(5);
257
add(avatarGroup);
258

259
// Collaborative form
260
UserInfo localUser = new UserInfo("user-123", "John Doe");
261
CollaborationBinder<Person> binder = new CollaborationBinder<>(
262
    Person.class, localUser, "person-789"
263
);
264
TextField nameField = new TextField("Name");
265
TextField emailField = new TextField("Email");
266

267
binder.forField(nameField).bind(Person::getName, Person::setName);
268
binder.forField(emailField).bind(Person::getEmail, Person::setEmail);
269

270
binder.setTopic("person-789", Person::new);
271

272
// Collaborative list
273
UserInfo localUser = new UserInfo("user-123", "John Doe");
274
CollaborationList<Task> taskList = new CollaborationList<>(
275
    CollaborationEngine.getInstance(),
276
    localUser, "tasks-project-456", Task.class
277
);
278

279
// Add item
280
taskList.appendItem(new Task("Review documentation"));
281

282
// Subscribe to changes
283
taskList.subscribe(new CollaborationListSubscriber<Task>() {
284
    @Override
285
    public void onItemInserted(int index, Task item, UserInfo user) {
286
        Notification.show(user.getName() + " added: " + item.getTitle());
287
    }
288

289
    @Override
290
    public void onItemUpdated(int index, Task item, UserInfo user) {
291
        Notification.show(user.getName() + " updated: " + item.getTitle());
292
    }
293

294
    @Override
295
    public void onItemRemoved(int index, Task item, UserInfo user) {
296
        Notification.show(user.getName() + " removed: " + item.getTitle());
297
    }
298
});
299

300
// Collaborative message list
301
UserInfo localUser = new UserInfo("user-123", "John Doe");
302
MessageList messageList = new MessageList();
303
MessageInput messageInput = new MessageInput();
304

305
CollaborationMessageList collaborationMessageList = new CollaborationMessageList(
306
    localUser, "chat-topic-123", messageList, messageInput
307
);
308

309
// Optional: custom submit handler
310
collaborationMessageList.setSubmitter((input, item) -> {
311
    // Custom submission logic
312
    item.setText(input.getValue());
313
    item.setTime(Instant.now());
314
    item.setUserName(localUser.getName());
315
});
316

317
add(messageList, messageInput);
318
```
319

320
## Messages
321

322
Chat and messaging components.
323

324
```java { .api }
325
class MessageList extends Component {
326
    MessageList();
327
    void setItems(List<MessageListItem> items);
328
}
329

330
class MessageListItem implements Serializable {
331
    MessageListItem();
332
    MessageListItem(String text);
333
    MessageListItem(String text, Instant time, String userName);
334
    void setText(String text);
335
    void setTime(Instant time);
336
    void setUserName(String userName);
337
    void setUserImage(String userImage);
338
    void setUserColorIndex(Integer colorIndex);
339
    void setUserAbbreviation(String abbreviation);
340
}
341

342
class MessageInput extends Component {
343
    MessageInput();
344
    void setPlaceholder(String placeholder);
345
    void setI18n(MessageInputI18n i18n);
346
    Registration addSubmitListener(ComponentEventListener<SubmitEvent> listener);
347
}
348

349
class SubmitEvent extends ComponentEvent<MessageInput> {
350
    String getValue();
351
}
352

353
class MessageInputI18n implements Serializable {
354
    void setSend(String send);
355
    void setMessage(String message);
356
}
357
```
358

359
**Example:**
360

361
```java
362
@Route("chat")
363
public class ChatView extends VerticalLayout {
364
    private MessageList messageList;
365
    private MessageInput messageInput;
366
    private List<MessageListItem> messages = new ArrayList<>();
367

368
    public ChatView() {
369
        messageList = new MessageList();
370
        messageList.setHeight("500px");
371

372
        messageInput = new MessageInput();
373
        messageInput.addSubmitListener(e -> addMessage(e.getValue()));
374

375
        add(messageList, messageInput);
376
        setSizeFull();
377
    }
378

379
    private void addMessage(String text) {
380
        MessageListItem msg = new MessageListItem(
381
            text, Instant.now(), "Current User"
382
        );
383
        msg.setUserAbbreviation("CU");
384
        msg.setUserColorIndex(2);
385
        messages.add(msg);
386
        messageList.setItems(messages);
387
        messageInput.setValue("");
388
    }
389
}
390
```
391

392
## Value Change Mode
393

394
```java { .api }
395
enum ValueChangeMode {
396
    EAGER,      // On every keystroke
397
    LAZY,       // On blur
398
    TIMEOUT,    // After timeout
399
    ON_BLUR,    // On blur
400
    ON_CHANGE   // On change
401
}
402
```
403

404
**Example:**
405

406
```java
407
TextField searchField = new TextField("Search");
408
searchField.setValueChangeMode(ValueChangeMode.LAZY);
409
searchField.setValueChangeTimeout(500);
410
searchField.addValueChangeListener(e -> performSearch(e.getValue()));
411
```
412

413
## Event Handling
414

415
```java { .api }
416
interface ComponentEventListener<E extends ComponentEvent<?>> extends Serializable {
417
    void onComponentEvent(E event);
418
}
419

420
class ClickEvent<T extends Component> extends ComponentEvent<T> {
421
    int getClientX();
422
    int getClientY();
423
    boolean isAltKey();
424
    boolean isCtrlKey();
425
    boolean isShiftKey();
426
}
427

428
class ComponentValueChangeEvent<C extends Component, V>
429
        extends ComponentEvent<C> implements HasValue.ValueChangeEvent<V> {
430
    V getOldValue();
431
    V getValue();
432
    boolean isFromClient();
433
}
434

435
interface Registration extends Serializable {
436
    void remove();
437
}
438
```
439

440
**Examples:**
441

442
```java
443
Button button = new Button("Save", e -> {
444
    if (e.isCtrlKey()) {
445
        saveAsDraft();
446
    } else {
447
        save();
448
    }
449
});
450

451
TextField field = new TextField("Name");
452
field.addValueChangeListener(e -> {
453
    String oldValue = e.getOldValue();
454
    String newValue = e.getValue();
455
    if (!newValue.equals(oldValue)) {
456
        validate(newValue);
457
    }
458
});
459
```
460

461
## Common Functional Interfaces
462

463
```java { .api }
464
@FunctionalInterface
465
interface ValueProvider<SOURCE, TARGET> extends SerializableFunction<SOURCE, TARGET> {
466
    TARGET apply(SOURCE source);
467
}
468

469
@FunctionalInterface
470
interface Setter<BEAN, VALUE> extends BiConsumer<BEAN, VALUE>, Serializable {
471
    void accept(BEAN bean, VALUE value);
472
}
473

474
@FunctionalInterface
475
interface ItemLabelGenerator<T> extends SerializableFunction<T, String> {
476
    String apply(T item);
477
}
478

479
@FunctionalInterface
480
interface SerializableFunction<T, R> extends Function<T, R>, Serializable {
481
    R apply(T t);
482
}
483

484
@FunctionalInterface
485
interface SerializableConsumer<T> extends Consumer<T>, Serializable {
486
    void accept(T t);
487
}
488

489
@FunctionalInterface
490
interface SerializablePredicate<T> extends Predicate<T>, Serializable {
491
    boolean test(T t);
492
}
493
```
494