Object Store Connector Reference | MuleSoft Documentation
# Object Store Connector Reference
Object Store Connector v1.2.0
Support Category: Select
Connector that provides functionality to access and create object store instances. 
## Configurations
### Config
Default configuration 
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The name for this configuration. Connectors reference the configuration with this name.  
Connection | The connection types to provide to this configuration.  
#### Connection Types
##### Connection
A ConnectionProvider that returns the Mule runtime's default ObjectStoreManager. 
###### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Reconnection |  | When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn't pass after exhausting the associated reconnection strategy.  
## Operations
  *   * Retrieve All Keys


### Clear
`<os:clear>`
Removes all the contents in the store.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition is used.  
#### Throws
  * OS:STORE_NOT_AVAILABLE


### Contains
`<os:contains>`
Checks if there is any value associated to the given key. If no value exists for the key, then false is returned.
This operation is synchronized at the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The key of the object to be checked.  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition is used.  
Target Variable | The name of a variable to store the operation's output.  
Target Value | An expression to evaluate against the operation's output and store the expression outcome in the target variable. | `#[payload]`  
#### Output
#### Throws
  * OS:INVALID_KEY
  * OS:STORE_NOT_AVAILABLE


### Remove
`<os:remove>`
Removes the value associated to the given key. If no value exists for the key, then an OS:KEY_NOT_FOUND error is thrown.
This operation is synchronized on the key level. No other operation is able to access the same key on the same object store while this operation is running.
If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The key of the object to be removed.  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition will be used.  
#### Throws
  * OS:INVALID_KEY
  * OS:STORE_NOT_AVAILABLE
  * OS:KEY_NOT_FOUND


### Retrieve
`<os:retrieve>`
Retrieves the value stored for the given key. If no value exists for the key, behavior depends on the defaultValue parameter.
If the parameter was not provided or was resolved to a null value, then an OS:KEY_NOT_FOUND error is thrown. Otherwise, the defaultValue is returned, but that value is not stored.
Finally, this operation is synchronized on the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The key of the value to be retrieved.  
Default Value | Value to be returned if the key doesn't exist in the store.  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition is used.  
Target Variable | The name of a variable to store the operation's output.  
Target Value | An expression to evaluate against the operation's output and store the expression outcome in the target variable. | `#[payload]`  
#### Throws
  * OS:INVALID_KEY
  * OS:KEY_NOT_FOUND
  * OS:STORE_NOT_AVAILABLE


### Retrieve All
`<os:retrieve-all>`
Retrieves all the key value pairs in the object store. 
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition is used.  
Target Variable | The name of a variable to store the operation's output.  
Target Value | An expression to evaluate against the operation's output and store the expression outcome in the target variable. | `#[payload]`  
#### Output
#### Throws
  * OS:STORE_NOT_AVAILABLE


### Retrieve All Keys
`<os:retrieve-all-keys>`
Returns a List containing all keys that the object store currently holds values for. 
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition is used.  
Target Variable | The name of a variable to store the operation's output.  
Target Value | An expression to evaluate against the operation's output and store the expression outcome in the target variable. | `#[payload]`  
#### Output
Array of String  
---  
#### Throws
  * OS:STORE_NOT_AVAILABLE


### Store
`<os:store>`
Stores the given value using the given key. This operation can be used either for storing new values or updating existing ones, depending on the value of the failIfPresent. When that parameter is set to `false` (default value), then any pre-existing value associated with that key is overwritten. If the parameter is set to `true`, then an `OS:KEY_ALREADY_EXISTS` error is thrown instead.
Another important consideration is regarding null values. It is not allowed to store a null value. However, a common use case is to obtain a value (most likely by evaluating a expression or transformation), testing the value for not null, storing it if present and doing nothing otherwise. The `failOnNullValue` parameter simplifies this use case. Setting it to `false` makes the connector skip null values, which prevents the need to use a `<choice/>` router to check the condition, while using the default value of `true` makes the connector throw a `NULL_VALUE` error.
Finally, this operation is synchronized on the key level. No other operation can access the same key on the same object store while this operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The key of the value to be stored.  
The value to be stored. Should not be null if `failOnNullValue` is set to true.  
Fail If Present | Whether to fail or update the pre-existing value if the key already exists on the store.  
Fail On Null Value | Whether to fail or skip the operation if the value is null.  
Object Store |  One of:
  *   * Object Store (Object Store v2)
  * Private Object Store

| A reference to the object store to use. If not defined, the runtime's default partition is used.  
#### Throws
  * OS:INVALID_KEY
  * OS:KEY_ALREADY_EXISTS
  * OS:NULL_VALUE
  * OS:STORE_NOT_AVAILABLE


## Types
### Reconnection
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Fails Deployment | When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.  
Reconnection Strategy | 
  *   * Reconnect Forever
| A reference to the object store to use. If not defined, the runtime's default partition is used.  
#### Throws
  * OS:INVALID_KEY
  * OS:KEY_ALREADY_EXISTS
  * OS:NULL_VALUE
  * OS:STORE_NOT_AVAILABLE


## Types
### Reconnection
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Fails Deployment | When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.  
Reconnection Strategy | 
  *   * Reconnect Forever

| The reconnection strategy to use.  
### Reconnect
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often in milliseconds to reconnect.  
How many reconnection attempts to make.  
blocking | If false, the reconnection strategy runs in a separate, non-blocking thread.  
### Reconnect Forever
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often in milliseconds to reconnect.  
blocking | If false, the reconnection strategy runs in a separate, non-blocking thread.  
### Object Store
These settings do not apply to Object Store v2.   
---  
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Persistent | Whether the store is persistent or transient.  
Max entries | The max number of entries allowed. Exceeding entries are removed when the expiration thread runs. If absent, then the described object store has no size boundaries.  
Entry ttl | The entry timeout. If absent, then the described object store has no time boundaries.  
Entry ttl unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

|  An entry’s time to live (`#entryTtl`).  
Expiration interval |  How frequently the expiration thread should run. The default value is 1 minute. The `expirationInterval` field requires that the `maxEntries` or `entryTtl` fields also be set. If neither is set, then putting a value in `Expiration Interval` has no effect and the expiration thread does not run. If `expirationInterval` is set to a value lower than or equal to zero, then the object store never expires.  
Expiration interval unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

|  The expiration interval (`#expirationInterval`).  
Configuration Reference |  Object Store Connector |  A reference to an `os:config` element used to declare this object store. If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.  
### Object Store (Object Store v2)
These settings apply only to Object Store v2.   
---  
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Persistent | Whether the store is persistent or transient.  
Max entries | **Not configurable for Object Store v2**. The maximum number of entries is unlimited.  
Entry ttl |  The entry timeout. Ignored if the value of `expirationInterval` is less than or equal to `0`.
  * Minimum value: 1 second
  * Maximum value: 30 days

If the field contains:
  * No value
    * Mule versions 4.2.1 and later: Rolling TTL
    * Mule versions earlier than 4.2.1: Static TTL of 30 days by default
  * Less than or equal to `0` TTL is static and set to the maximum value (2592000 seconds/30 days).
  * Positive number TTL is static and set to the specified value (between 1 and 2592000 seconds)
  * Greater than 30 days TTL is static and set to the maximum value (2592000 seconds/30 days).

For information about the rolling and static TTL behavior, see Time to Live (TTL). | 2592000 seconds (30 days)  
Entry ttl unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

|  The unit for the entry’s time to live (`entryTtl`).  
Expiration interval |  Positive number |  How frequently the expiration thread runs. The `expirationInterval` field requires that the `entryTtl` field is set; otherwise, it is ignored.
  * If `expirationInterval` is set to a positive value less than the value of `entryTtl`, the entry expires based on the `entryTtl` configuration.
  * If `expirationInterval` is set to a value less than or equal to zero, `entryTtl` is ignored.

| 1 minute  
Expiration interval unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

|  The expiration interval (`expirationInterval`).  
Configuration Reference |  Object Store Connector |  A reference to an `os:config` element used to declare this object store. If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.  
### Object Store Connector
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Config Name  
### Private Object Store
These settings do not apply to Object Store v2.   
---  
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
A friendly name to refer to this store in the management user interface. Provide this alias if you would like it to be easier to identify this store. If not provided, Mule auto generates an ID. Use an alias for consistent OAuth token refresh behavior. Without an alias, each Mule app node creates its own partition. This can lead to issues with OAuth token refresh, as each node might try to refresh the token independently. By providing an alias, you make sure that the Mule app uses the same partition across restarts. As long as the cached key or value is not expired, the caching scope is hit, and the Mule app continues to use the same token. This prevents unnecessary token refreshes and improves application efficiency.  
Persistent | Whether the store is persistent or transient.  
Max entries | The maximum number of entries allowed. Exceeding entries are removed when the expiration thread runs. If absent, then the described object store has no size boundaries.  
Entry ttl | The entry timeout. If absent, then the described object store has no time boundaries.  
Entry ttl unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

|  An entry’s time to live (`#entryTtl`).  
Expiration interval | How frequently the expiration thread should run. The default value is 1 minute. The `expirationInterval` field requires that the `maxEntries` or `entryTtl` fields also be set. If neither is set, then putting a value in `expirationInterval` has no effect and the expiration thread does not run. If `expirationInterval` is set to a value lower than or equal to zero, then the object store never expires.  
Expiration interval unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

|  The expiration interval (`#expirationInterval`).  
Configuration Reference |  Object Store Connector |  A reference to an `os:config` element which is used to declare this object store. If not provided, the Mule runtime’s default ObjectStoreManager is used. Setting this parameter is necessary only when you want to use a nondefault object store implementation: for example, if you want to have a store that is backed by Redis or JDBC.  
## See Also
  * MuleSoft Help Center