Nav

Object Store Connector

Introduction

The Object Store Connector lets you connect to the object storage facility in Mule and exposes convenient methods for exploiting the capabilities of Mule Object Stores. Internally, Mule uses object stores in various filters, routers, and other message processors that need to store state between messages.

Read through this user guide to understand how to set up and configure a basic flow using the connector. Read through the Technical Reference to understand how the connector operations interact with Mule Object Stores. You can also find demo applications here that illustrate how to use the connector operations. Release Notes are a good way to track feature additions, compatibility limitations, and API version updates with each release of the connector version.

MuleSoft maintains this connector under the Select support policy.

Prerequisites

This document assumes that you are familiar with Mule, the Anypoint Studio InterfaceGlobal Elements, and DataSense.

Requirements

For hardware and software requirements, please visit MuleSoft.com.

For information on object store data limits, see: Semantics and Storage Limits.

Namespace and Schema

When designing your application in Studio, the act of dragging the connector from the palette onto the Anypoint Studio canvas should automatically populate the XML code with the connector namespace and schema location.

Namespace

xmlns:objectstore="http://www.mulesoft.org/schema/mule/objectstore"

Schema Location

http://www.mulesoft.org/schema/mule/object/current/mule-objectstore.xsd

For example, see how the XML is configured to include the connector namespace and schema location in the application:


          
       
1
2
3
4
5
6
7
8
9
10
11
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:objectstore="http://www.mulesoft.org/schema/mule/objectstore"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/objectstore
               http://www.mulesoft.org/schema/mule/objectstore/current/mule-objectstore.xsd">
  
      <!-- Insert your configuration elements and your flow here -->
</mule>

Compatibility

The Object Store connector is compatible with:

Application/Service Version

Mule Runtime

3.6.0 or newer

Anypoint Studio

5.2 or newer

Starting with version 2.0.0, the Object Store connector is licensed commercially with Anypoint Platform as with other Select connectors. Prior versions remain freely available to the community.

Installing the Object Store Connector

You can install the connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

About the Object Store Spring Bean Instances

By default, Mule includes three default object stores instantiated every time you run Mule both on premises and on Runtime Manager.

Each Mule runtime includes these three spring bean instances:

  • _defaultInMemoryObjectStore

  • _defaultUserObjectStore

  • _defaultTransientUserObjectStore

You can also code your own object store Java class, then include an instance in your application as a Spring bean. You can then reference your custom object store when you define a new Object Store global element.

Important: If you want your Object Store data to display in Runtime Manager’s Application Data user interface, you must include the objectStore-ref="_defaultUserObjectStore" parameter in your Object Store connector configuration.

About Persisting Object Stores in Runtime Manager

The Persistent option persists data for Private Cloud Edition (on premise) applications; however to persist data in Runtime Manager, you need to use the _defaultUserObjectStore spring bean instance in your ObjectStore configuration.

The _defaultUserObjectStore spring bean instance ensures that an Object Store in a Runtime Manager application survives across redeployments. When you use this bean instance, data persists outside the Runtime Manager worker (but in the cloud), which is why the data is available after restarts.

Reference the spring bean instance using the Object Store Reference field.

For XML or standalone use, add the objectStore-ref="_defaultUserObjectStore" parameter, for example:


          
       
1
2
3
<objectstore:config name="ObjectStore__Connector" partition="mypartition"
entryTtl="0" expirationInterval="42" maxEntries="42"
objectStore-ref="_defaultUserObjectStore" doc:name="ObjectStore: Connector"/>

The use of _defaultUserObjectStore makes entries visible in Runtime Manager through Application Data.

Differences between using the Persistent parameter and _defaultUserObjectStore:

Site Attribute "persistent": Using _defaultUserObjectStore

Private Cloud Edition

  • Survives redeployments

  • Data persists in a local file

  • Survives redeployments

  • Data persists in a local file

In Runtime Manager

  • Does not survive redeployments

  • Data persists in a local file

  • Survives redeployments

  • Data persists externally

Setting up the Global Configuration Using Studio Visual Editor

Configure a global Object Store element that can be used by all instances of the Object Store connector in your application.

  1. If you haven’t already, read about Global Elements before proceeding further.

  2. Click the Global Elements tab at the base of the canvas.

  3. On the Global Mule Configuration Elements screen, click Create.

  4. In the Choose Global Type wizard, expand Connector Configuration and select ObjectStore: Configuration and click Ok.

    Global Element Configuration Wizard

  5. Configure the parameters according to your needs. This is the screen you configure the connector global element from:

    Global Element Configuration

    [%header,cols="30a,70a"

Parameter

Description

Name

(Required) Enter a name for the configuration to reference it.

Partition

(Required) Name of the partition in the default in-memory or persistent object stores. Important: You must specify a partition name in your configuration.

Object Store Reference

Specify the Object Store spring bean instance. This is optional and if not specified, the default in-memory or persistent store is used. See About the Object Store Spring Bean Instances.

Entry Ttl

TimeToLive for stored values in milliseconds. "Max Entries" and "Expiration Interval" are mandatory for using this param. You must either provide all Entry TTL, Max Entries, and Expiration Interval, or none of them.

Expiration Interval

Specifies the expiration check interval in milliseconds.

Max Entries

Specifies the maximum number of entries.

Persistent

Specified whenever the required store needs to be persistent or not. See About Persisting Object Stores in Runtime Manager.

+ Note: In the image above, the placeholder values refer to a configuration file placed in the src folder of your project. See Learn how to configure properties.

+ You can either enter your credentials into the global configuration properties, or reference a configuration file that contains these values. For simpler maintenance and better re-usability of your project, Mule recommends that you use a configuration file. Keeping these values in a separate file is useful if you need to deploy to different environments, such as production, development, and QA, where your access credentials differ. See Deploying to Multiple Environments for instructions on how to manage this. . Click OK to save the global connector configurations.

Setting up the Global Configuration Using XML

Follow these steps to configure the connector in your application: Create a global Object Store configuration outside and above your flows, using the following global configuration code.

<objectstore:config name="ObjectStore__Configuration" partition="${objectstore.partition.counter}" doc:name="ObjectStore: Configuration"/>
When you manually code the Mule application in Studio’s XML editor or another text editor, paste these into the header of your Configuration XML inside the <mule> tag as in the example below.
Name Description

name

The identifier of the object store configuration. Other components must reference this configuration via this name.

Studio Field: Name
Default: none
Java Type: String
MIME Type: /
Encoding: UTF-8

doc:name

The string displayed in Anypoint Studio.

Studio Field: Name
Default: none
Java Type: String
MIME Type: /
Encoding: UTF-8

partition

Unique name of the partition in the default in-memory or persistent object store. Important: You must specify a partition name in your configuration.

Studio Field: Partition
Default: none
Java Type: String
MIME Type: /
Encoding: UTF-8

objectStore-ref

Optional. Reference to an object store spring bean instance. Use an instance depending on the context (stand-alone Mule runtime, Mule runtime cluster, or CloudHub cluster). You can also specify one of the default object stores by name _defaultInMemoryObjectStore, _defaultUserObjectStore, or _defaultTransientUserObjectStore. See About the Object Store Spring Bean Instances. Note: You must specify _defaultUserObjectStore to get data to display in Runtime Manager’s Application Data user interface.

Studio Field: Object Store Reference
Default: none
Java Type: String
MIME Type: none
Encoding: none

entryTtl

Time To Live for stored values in milliseconds. If using this parameter, maxEntries, and expirationInterval are mandatory.

Studio Field: Entry Ttl
Default: none
Java Type: Int
MIME Type: /
Encoding: UTF-8

expirationInterval

Specifies the expiration check interval in milliseconds.

Studio Field: Expiration Interval
Default: none
Java Type: Int
MIME Type: /
Encoding: none

maxEntries

Specifies the maximum number of entries.

Studio Field: Max Entries
Default: none
Java Type: Int
MIME Type: /
Encoding: none

persistent

Specifies if the required store needs to be persistent or not (this argument is ignored if the object store is passed by reference using the objectStore-ref attribute, or if no partition name is defined). If persistent is false, then data may be lost when a Mule runtime restarts. See About Persisting Object Stores in Runtime Manager.

Studio Field: Persistent (checkbox)
Default: false
Java Type: boolean
MIME Type: /
Encoding: none

The following is an example objectstore configuration that specifies a partition named customers within the defaultUserObjectStore, and specifying that the object store should be persistent.

<objectstore:config name="ObjectStore__Configuration" partition="customer"  persistent="true"/>

If you do not specify a value for the objectstore-ref, the _defaultUserObjectStore is used, which is equivalent to this configuration:

<objectstore:config name="ObjectStore__Configuration" objectstore-ref="_defaultUserObjectStore"  persistent="true"/>

If you don’t want to use one of the default object stores, you can define your own Java bean and reference it instead in the objectstore-ref attribute.

Updating from an Older Version

If you’re currently using an older version of the connector, a small popup appears in the bottom right corner of Anypoint Studio with an "Updates Available" message.

  1. Click the popup and check for available updates. 

  2. Click the Object Store connector checkbox for the version you require and click Next, following the instructions provided by the user interface. 

  3. Restart Studio when prompted. 

  4. After restarting, when creating a flow and using the Object Store connector, if you have several versions of the connector installed, you may be asked which version you would like to use. Choose the version you would like to use.

We recommend that you keep Studio up to date with its latest version. 

Using This Connector

The Object Store connector is an operation-based connector, which means that when you add the connector to your flow, you need to configure a specific operation for the connector to perform. See the entire operation processors list in the github.io or click individually on the listed operations below. The connector currently supports the following list of operations, each requiring certain attributes to be set:

The Dual store operation may be misleading. The function of this operation is to do 2 writes to object store, the first with objectStore.store(key, value) and the second with the objectStore.store(value, key) operation.

Adding to a Flow

  1. Create a new Mule Project in Anypoint Studio.

  2. Add a suitable Mule Inbound Endpoint, such as the HTTP listener or File endpoint, to begin the flow.

  3. Drag and drop the Object Store connector onto the canvas.

  4. Click on the connector component to open the Properties Editor.

    Flow Settings

  5. Configure the following parameters:

    Field Description

    Basic Settings

    Display Name

    Enter a unique label for the connector in your application.

    Connector Configuration

    Connect to a global element linked to this connector. Global elements encapsulate reusable data about the connection to the target resource or service. Select the global Object Store connector element that you just created.

    Operation

    Select Store from the drop-down menu.

    General

    Key

    The identifier of the object to store.

    Value Reference

    The object to store.

  6. Save your configurations.

Example Use Case

After installing and configuring the Object Store connector, use it in a Mule flow to store and retrieve employee data.

The following Mule App stores employee data containing employee identifier, first name, last name and age in JSON format using the Object Store connector. The Mule app has two HTTP endpoints.

  • /store: Used to store employee data

  • /retrieve: Get employee data for the identifier mentioned. Store and Retrieve Employee data

Lets start with the flow to store employee data.

  1. Create a new Mule Project in Anypoint Studio.

  2. Drag a HTTP connector onto the canvas and configure the following parameters:
    objectstore http config props for store endpoint

    Parameter Value

    Display Name

    HTTP

    Connector Configuration

    If no HTTP element has been created yet, click the plus sign to add a new HTTP Listener Configuration and click OK (leave the values to its defaults).

    Path

    /store

  3. Next, drag the Object Store connector next to the Transform Message component and configure it according to the steps below:

  4. Click the plus sign next to the Connector Configuration field to add a new Object Store Global Element.

    1. Configure the global element according to the table below:

      Parameter Description Value

      Name

      Enter a name for the configuration to reference it.

      <Configuration_Name>

      Partition

      Name of the partition

      employees

    2. The corresponding XML configuration should be as follows:

      <objectstore:config name="ObjectStore__Configuration" partition="employees" doc:name="ObjectStore: Configuration"/>
  5. Back in the properties editor of the Object Store connector, configure the remaining parameters:

    Parameter Value

    Basic Settings

    Display Name

    Store employee (or any other name you prefer).

    Connector Configuration

    ObjectStore__Configuration (the reference name to the global element you have created).

    Operation

    Store

    General

    Key

    #[message.inboundProperties.'http.query.params'.id]

    Value Reference

    #[payload]

  6. Check that your XML looks as follows:

    <objectstore:store config-ref="ObjectStore__Configuration" key="#[message.inboundProperties.'http.query.params'.id]" value-ref="#[payload]" doc:name="Store employee"/>
  7. Similarly, drag another Object Store connector to get all keys from Store.

  8. Configure the properties editor accordingly to the table below:

    Parameter Value

    Basic Settings

    Display Name

    Get all keys (or any other name you prefer).

    Connector Configuration

    ObjectStore__Configuration (the reference name to the global element you have created).

    Operation

    All keys

  9. Check that your XML looks as follows:

    <objectstore:all-keys config-ref="ObjectStore__Configuration" doc:name="Get all keys"/>
  10. Add a Logger scope after the Object Store connector to print the data that is being passed by the All keys operation in the Mule Console. Configure the Logger according to the table below.

    Parameter Value

    Display Name

    Log Employee IDs (or any other name you prefer)

    Message

    Keys : #[payload]

    Level

    INFO

  11. Add a Set Payload after the logger component. Configure the component according to the table below.

    Parameter Value

    Display Name

    Show Employee IDs (or any other name you prefer)

    Message

    Keys : #[payload]

    Level

    INFO

Now lets add another flow to retrieve employee data stored previously.

  1. Drag a Flow Component below the above flow.

  2. Drag a HTTP connector onto the canvas and configure the following parameters:

    objectstore http config props for retrieve endpoint

    Parameter Value

    Display Name

    HTTP

    Connector Configuration

    Use the already available configuration .

    Path

    /retrieve

  3. Drag the Object Store connector and configure it according to the steps below:

    Parameter Value

    Basic Settings

    Display Name

    Store employee (or any other name you prefer).

    Connector Configuration

    ObjectStore__Configuration (the reference name to the global element you have created).

    Operation

    Retrieve

    General

    Key

    #[message.inboundProperties.'http.query.params'.id]

  4. Check that your XML looks as follows:

    
                
             
    1
    
    <objectstore:retrieve config-ref="ObjectStore__Configuration" key="#[message.inboundProperties.'http.query.params'.id]" doc:name="Retrieve Employee"/>
  5. Add a Logger scope after the Object Store connector to print the data that is being retrieved in the previous operation to the Mule Console. Configure the Logger according to the table below.

    Parameter Value

    Display Name

    Log Employee data (or any other name you prefer)

    Message

    Keys : #[payload]

    Level

    INFO

  6. Add a Set Payload after the logger component. Configure the component according to the table below.

    Parameter Value

    Display Name

    Show Employee data (or any other name you prefer)

    Message

    Keys : #[payload]

    Level

    INFO

Example Code

Paste this code into your XML Editor to quickly load the flow for this example use case into your Mule application.


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:objectstore="http://www.mulesoft.org/schema/mule/objectstore" xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:spring="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/objectstore http://www.mulesoft.org/schema/mule/objectstore/current/mule-objectstore.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <objectstore:config name="ObjectStore__Configuration" partition="employees" doc:name="ObjectStore: Configuration"/>
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <flow name="objectstore-store-employee-flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/store" doc:name="HTTP"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/json
---
{
                id: inboundProperties.'http.query.params'.id,
                name: inboundProperties.'http.query.params'.name,
                lname: inboundProperties.'http.query.params'.lname,
                age: inboundProperties.'http.query.params'.age
}]]></dw:set-payload>
        </dw:transform-message>
        <objectstore:store config-ref="ObjectStore__Configuration" key="#[message.inboundProperties.'http.query.params'.id]" value-ref="#[payload]" doc:name="Store employee"/>
        <objectstore:all-keys config-ref="ObjectStore__Configuration" doc:name="Get all keys"/>
        <logger message="Keys : #[payload]" level="INFO" doc:name="Log Employee Id's"/>
        <set-payload value="Keys : #[payload]" doc:name="Show Employee Id's"/>
    </flow>
    <flow name="objectstore-retrieve-employee-flow">
        <http:listener config-ref="HTTP_Listener_Configuration" path="/retrieve" doc:name="HTTP"/>
        <objectstore:retrieve config-ref="ObjectStore__Configuration" key="#[message.inboundProperties.'http.query.params'.id]" doc:name="Retrieve Employee"/>
        <logger message="Employee: #[payload]" level="INFO" doc:name="Log Employee"/>
        <set-payload value="Employee : #[payload]" doc:name="Show Employee"/>
    </flow>
</mule>

Run Time

  1. Save and run the project as a Mule Application.

  2. Open a web browser and enter the below to check the response.

    1. To store a employee record enter the URL:
      http://localhost:8081/store?id=1&name=David&lname=Malhar&age=10.

    2. To retrieve a employee record enter the URL:
      http://localhost:8081/retrieve?id=1

      The logger displays the employee record in JSON format in the browser.

  • The object store throws an exception when an attempt is made to overwrite an existing key; this is expected behavior. The object store throws an exception when an attempt to read is made using a key that does not exist in the object store; this too is expected; this is also expected behavior.

  • This example uses a simple in-memory store; to clear the contents of this store, restart Mule runtime.

Demo

You can download another fully functional example from this link.

Using the Connector in a Mavenized Mule App

If you are coding a Mavenized Mule application, this XML snippet must be included in your pom.xml file.


         
      
1
2
3
4
5
<dependency>
  <groupId>org.mule.modules</groupId>
  <artifactId>mule-module-objectstore</artifactId>
  <version>2.0.0</version>
</dependency>

Inside the <version> tags, put the desired version number, the word RELEASE for the latest release, or SNAPSHOT for the latest available version. The available versions to date are:

  • 2.0.1

  • 2.0.0

  • 1.3.3

  • 1.3.2

See Also