Store and Retrieve Information in an Object Store Example

The Object Store connector provides Store (<os:store/>) and Retrieve (<os:retrieve/>) operations.

Target variables used with the Object Store connector are described in the Mule Runtime Target Variables document.

Store Information from the Object Store

You can use an Object Store to store values like this:

<os:store key="state">
  <os:value>
    <![CDATA[#[
      output application/json
       ---
       {
          "id": attributes.queryParams.id,
          "timestamp": now(),
          "name": payload.name
        }
      ]]]>
  </os:value>
</os:store>

You can use the Store operation to store new values or update existing ones, depending on the value of the failIfPresent parameter. When this parameter is set to false (the default), any pre-existing value associated to that key is overwritten. If the parameter is set to true, then an OS:KEY_ALREADY_EXISTS error is thrown instead.

Note that it is not possible to store null values. However, it is common to obtain a value by evaluating an expression or transformation:

Testing that the value is not null.
Storing the value if it is present.
Otherwise, doing nothing.

The failOnNullValue parameter simplifies this use case. By default (true), a OS:NULL_VALUE error is thrown if a null value is supplied. However, when the parameter is set to false, a null value causes this operation to do nothing: No error is raised, and no value is altered.

Retrieve Information from the Object Store

The Retrieve operation retrieves the value for a given Object Store key. By default, the retrieved value becomes the message payload. To keep the current payload and store the retrieved value in a variable instead, use the target parameter (for example, target="myVar" so you can access the value as vars.myVar). See Set Up Watermarks with an Object Store for an example that uses target to avoid overriding the payload.

Use the Retrieve operation to read previously stored data in a flow, for example, to resume state, reuse cached values, or pass stored data to the next operation. For all parameters (including objectStore, target, and targetValue), see the Retrieve operation in the connector reference.

You can use the key to retrieve single values:

<os:retrieve key="userId" />

The operation returns the stored value (or the default value, if provided). When you don’t use the target parameter, that value becomes the new message payload for the rest of the flow.

You can use an operation like this one to provide default values when the key is not present in the store:

<os:retrieve key="timestamp">
  <os:default-value>#[now()]</os:default-value>
</os:retrieve>

You can have default, complex structures:

<os:retrieve key="state">
  <os:default-value>
    <![CDATA[#[
     output application/json
     ---
     {
        "id": attributes.queryParams.id,
        "timestamp": now(),
        "name": payload.name
      }
    ]]]>
  </os:default-value>
</os:retrieve>

Note that the defaultValue parameter handles cases in which no value exists for a given key. If you do not provide the parameter and the operation resolves to a null value, an OS:KEY_NOT_FOUND error is thrown. Otherwise, the defaultValue is returned but not stored.

All Object Store operations are synchronized at the key level. No other operation is able to access the same key on the same Object Store while the operation is running. If the runtime is running in cluster mode, this synchronization is also guaranteed across nodes.