# Store

The **Store** interface defines a per-session key-value storage abstraction for socketio4j.\
It allows transports, namespaces, and user code to persist small pieces of session-scoped metadata such as user IDs, authentication tokens, connection state, or room membership hints—independent of the actual backing storage implementation.

**Key characteristics**

* **Session-scoped storage** — one store instance exists per connected client session
* **Key-value semantic** — arbitrary objects associated with string keys
* **Backend-agnostic** — implementations may use memory, Hazelcast, Redis, or other data stores
* **Lifecycle-aware** — destroyed when the underlying client disconnects
* **Type-safe retrieval** — returned values can be cast or generically typed

**How it works**

* `set` associates a value with a key for the lifetime of the session
* `get` returns a stored value, or `null` if not present
* `has` checks for key existence without loading the value
* `del` removes a single key-value entry
* `destroy` removes all entries, invalidating the store instance

**Usage scenarios**

| Case                        | Example                                             |
| --------------------------- | --------------------------------------------------- |
| Authentication              | store `"userId"`, `"tenant"`, `"tokenClaims"`       |
| Reconnection hints          | store `"rooms"` or custom metadata                  |
| Custom handshake parameters | persist user metadata from upgrade/handshake        |
| Namespaced logic            | attach state needed only during the current session |

**Advantages**

👍 Works uniformly across clustered and standalone modes\
👍 Keeps session metadata isolated to each connection\
👍 Allows switching storage backend without user code changes\
👍 Supports lightweight in-memory operation for single-node deployments

**Limitations**

ℹ️ Not intended for large objects or binary storage\
ℹ️ Not a distributed data model by itself — distribution depends on implementation\
ℹ️ No built-in TTL or expiration beyond session lifecycle\
ℹ️ Not shared across sessions unless backed by shared storage

***

#### Backend behavior

| Backend                                           | Persistence                                     | Visibility              | Characteristics                        |
| ------------------------------------------------- | ----------------------------------------------- | ----------------------- | -------------------------------------- |
| **In-memory**                                     | Ephemeral, cleared on disconnect or JVM restart | Local only              | Fastest, best for single node          |
| **Hazelcast / Redis(redis, valkey, dragonflydb)** | Distributed (based on backend config)           | Accessible across nodes | Recommended for multi-node deployments |

***

#### Lifecycle guarantee

> **A Store instance lives for exactly one client session and is destroyed when the session ends.**\
> After calling `destroy()`, the store must not be accessed again.
>
> Automatically called when client disconnects.

#### Example

```
server.addEventListener("storeDemo", String.class,
        (client, data, ackSender) -> {

    // ----- SET -----
    client.getStore().set("key1", data);
    log.info("SET key1 = {}", data);

    // ----- GET -----
    String value = client.getStore().get("key1");
    log.info("GET key1 = {}", value);

    // ----- HAS -----
    boolean existsBefore = client.getStore().has("key1");
    log.info("HAS key1 (before delete) = {}", existsBefore);

    // ----- DEL -----
    client.getStore().del("key1");
    log.info("DEL key1");

    // ----- HAS again -----
    boolean existsAfter = client.getStore().has("key1");
    log.info("HAS key1 (after delete) = {}", existsAfter);

});

```