# 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);

});

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.socketio4j.org/adapters/introduction/store.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.