Overview

To maximize efficiency when interacting with external data sources, such as databases or remote sites, the Mirror Service allows different runtime spaces to push write operations in an asynchronous manner into a central service that can aggregate the operations and persist these into a file or a database or to be sent to remote sites. When the Mirror Service used to persist data the operations are persisted into the underlying database in one bulk operation. This activity is sometimes referred to as a Write-Behind operation.

New in Version 5.1 The Mirror Service is a new feature, supported in GigaSpaces version 5.1 and onwards.

Mirror Space

The Mirror Service is based on a regular space, the mirror space with special capabilities that allow it to get data from clustered spaces without explicitly being defined as part of the cluster members list.

The following is a basic schematic flow of a synchronous replicated cluster communicating with a mirror service:

Running Mirror Service

To Start the Mirror Service run the following:

gsInstance "/./mirror-service?schema=mirror&properties=mirror" "${APPLICATION_JARS}"

Where APPLICATION_JARS should include the application libraries.

Running a Cluster in Mirror Mode

The mirror option for a the runtime space is turned on by the mirror URL property. In order to be able to use the mirror service, a space must be started using the mirror URL property.
Below is an example of starting partitioned clustered space with 2 partitions with one backup per partition topology in mirror mode:

gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=1&mirror"
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=2&mirror"
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=1&backup_id=1&mirror"
gsInstance "/./mySpace?cluster_schema=partitioned-sync2backup&total_members=2,1&id=2&backup_id=1&mirror"

You can have some of your cluster members mirror their data, and some not. The ones you want to mirror should have the mirror URL used when starting the space.

Below is an example of starting synchronous replicated clustered space with 2 nodes running in mirror mode pushing data into the Mirror Service:

gsInstance "/./mySpace?cluster_schema=sync_replicated&total_members=2&id=1&mirror"
gsInstance "/./mySpace?cluster_schema=sync_replicated&total_members=2&id=2&mirror"

Since the Mirror Service uses under the hood the asynchronous replication facility, in case it is shut down or failed and later restarted in the same original machine or in a different machine (using the Service Grid in a transparent manner), the operations that occurred during the shutdown time period will be replayed from the source spaces redo log into the mirror space. Therefore, there is no data loss.

Writing to Database

The object mapping into the database tables in the Mirror Service can be done via Hibernate, which uses the Hibernate BulkStore bulk operation interface provided with the product. In case the default Hibernate BulkStore interface is not adequate, users can implement the CacheBulk.store method for their own business logic mapping.

The CacheBulk.store method works only with a Mirror space. The underlying mechanism when using the Mirror space is very different than a regular space. The data pushed in the CacheBulk.store can come only as a result of replication from a primary space, and not as a result of a user writing into the Mirror space. Data written into the mirror space is not stored inside the space and isn't sent to the CacheBulk.store.

Read Operations

The Mirror Service can be used together with the CacheLoader for read operations. This allows an application to load data implicitly and store data asynchronously from the same database. This architecture provides good read and write performance since the database access time would not affect write, update, or take operations.

Each cluster can have a default Mirror Service URL (that could be modified via the cluster schema file) with relevant replication settings to be used when pushing the data into the Mirror Service where each started cluster node could have the Mirror Service enabled or disabled using the mirror URL property.

The cluster schema should have the following:

<cluster-config>
	<mirror-service>
		<enabled>true</enabled>
		<url>jini://*/mirror-service_container/mirror-service</url>
		<bulk-size>100</bulk-size>
		<interval-millis>2000</interval-millis>
		<interval-opers>100</interval-opers>
	</mirror-service>
</cluster-config>

The Mirror Service allows users to run the Mirror space on a machine that is running the database in a separate JVM, allowing the runtime spaces to perform their operations with minimal impact on performance when persisting the data. Since the loopback adaptor allows different processes running on the same machine to communicate in very fast manner, the communication between the Mirror Service and the database will be faster than a pure remote call when mirror service and database running on different machines.

Non Mirrored Entries

When using the mirror service, you might not want to replicate all space Entries into the mirror service to be persistent or to be delivered to some external data source. The mirror service does not persist or deliver to an external data source (do not pass into com.j_spaces.javax.cache.CacheBulk.store(List<CacheBulk.BulkEntry>)) Entry that has been identified as transient.

A transient entry can be constructed by extending your Entry class from com.j_spaces.core.client.MetaDataEntry, and calling the MataDataEntry.makeTransient() method when constructing the Entry.

Configuration

The space running as a mirror service should have the following properties set:

space-config.mirror-service.enabled=true
space-config.persistent.enabled=true
space-config.persistent.CacheLoaderClass=com.pack.myMirrorImpl
space-config.persistent.StorageAdapterClass=com.j_spaces.sadapter.cache.CacheAdapter
space-config.persistent.force-cold-init=false
space-config.engine.cache_policy=0

The com.pack.myMirrorImpl should be an implementation of the com.j_spaces.javax.cache.CacheBulk Interface.

Considerations and Known Issues

The following limitations exist for the Mirror Service:

• The Mirror Service cannot be a clustered space.
• Memory Recovery cannot be done using the Mirror Service.
• The Mirror Service cannot be used with a single space or the partitioned cluster schema. It is supported with the sync-replicated, async-replicated and partitioned-sync2backup cluster schemas.

Asynchronous Write-Behind Cache to Database Using Mirror Service

This section discusses using JavaSpaces API with a mirror space to enable asynchronous write-through operations.

Write-Behind Cache to Database Using CacheBulk.store

The figure above illustrates how a client application writes Entry object data to a space and persists the data asynchronously into a database using a user-implemented CacheBulk interface.
The operation proceeds in two stages:

1. The client application calls destructive operation (i.e. JavaSpace.write , JavaSpace.take or IJSpace.update) methods, passing the Entry object.
2. The JavaSpace API writes the Entry object data as a space Entry. The data in the space is replicated asynchronously to a Mirror Space for writing to the database. The write operation from Mirror Space to the database is not executed immediately but rather is accumulated with other operations pending in the redo log and waits for the asynchronous replication of data to the mirror space. In the redo log the operations and data are stored as a Set of CacheBulk.BulkEntry objects, similar to transaction objects (in case of an actual transaction, the data is synchronized for immediate database update when the transaction is committed). When the redo log is full, the CacheBulk Interface method store operates synchronously and writes the entire collection of operations stored in the redo log at once. The store method, which is implemented by the user, extracts the Entry and operation data and uses the JDBC API to perform the required operation on the database, transforming the IGSEntry object data into the corresponding record format.

The above is relevant also for all other APIs supported – Map, JDBC, and JMS

CacheBulk as a Mirror Implementation When implementing the CacheBulk as a Mirror implementation and extending the AbstractCacheLoader, you should return null from the load method and new HashMap() from the loadAll method.

When using the AbstractCacheLoader.getConverter().toObject(IGSEntry), your Entry must include getter and setter methods.

Asynchronous Write-Behind Cache to Database Using Hibernate

The figure above illustrates how a client application writes Entry object data to a space and persists the data asynchronously in a database using the Hibernate CacheBulk interface.
The operation proceeds in two stages:

1. The client application calls destructive operation (i.e. JavaSpace.write , JavaSpace.take or IHSpace.update) methods, passing the Entry object.
2. The JavaSpace API writes the Entry object data as a space Entry. The data in the space is replicated asynchronously to a mirror space for writing to the database. The write operation is not executed immediately from the mirror space to the database, but rather is accumulated with other operations pending in the redo log and waits for the asynchronous replication of data to the mirror space. In the redo log the operations and data are stored as as a set of CacheBulk.BulkEntry objects, similar to transaction objects (in case of an actual transaction, the data is synchronized for immediate database update when the transaction is committed). When the redo log is full, the Hibernate Cache Bulk Store Interface method store operates synchronously and writes the entire collection of operations stored in the redo log at once. The store method, which is not implemented by the user, uses the Hibernate O/R database connection functions to perform either an insert, update or remove operation on the database, transforming the IGSEntry object data into the corresponding record format.

Configuration

The space running as a mirror service using Hibernate to persist the operations should have the following properties set:

space-config.mirror-service.enabled=true
space-config.persistent.enabled=true
space-config.persistent.CacheLoaderClass=com.gigaspaces.hibernate.HibernateCacheStoreImpl
space-config.persistent.StorageAdapterClass=com.j_spaces.sadapter.cache.CacheAdapter
space-config.persistent.force-cold-init=false
space-config.engine.cache_policy=0

Running Mirror Service as Service Grid Service

Download this example, where the Service Grid Deployment Descriptor deploys sync-replicated spaces and a mirror service into the Service Grid.

To run the example, extract the example file into <GigaSpaces Root>\ServiceGrid\examples, and follow the instructions described in the <GigaSpaces Root>\ServiceGrid\examples\mirror\readme.txt file.

Once you deploy the example, you should see the following in the Service Grid UI:

Troubleshooting

For details about viewing the exact configuration in which the system is currently running, refer to the Container Maintenance section.

Log Messages

When a clustered space started in Mirror enabled mode (using the mirror Space URL property) it should log the following:

CONFIG [com.gigaspaces.persistent]:
Life-cycle properties:
         Supports inheritance: true
         Supports versioning:  false


CONFIG [com.gigaspaces.persistent]:
schema-xml configuration:
<persistent>
         <CacheLoaderClass>com.gigaspaces.hibernate.HibernateCacheStoreImpl</CacheLoaderClass>
         <StorageAdapterClass>com.j_spaces.sadapter.cache.CacheAdapter</StorageAdapterClass>
         <entity-class></entity-class>
</persistent>
cluster-xml configuration:
<cache-loader>
         <external-data-source>false</external-data-source>
         <central-data-source>false</central-data-source>

When a space running as a Mirror Service started it should log the following:

INFO [com.gigaspaces.core.cluster.replication]:
        Mirror Service Connector : Started
                Source space     : HC_container1:HC
                Mirror URL       : jini://*/mirror-service_container/mirror-service?groups=gigaspaces-5.1EE
                BulkSize         : 100
                IntervalMillis   : 2000
                IntervalOpers    : 100

When the Mirror Service established connection to a space requesting Mirror services (mirror URL property used when started) it should log the following:

Joined new [HC_container1:HC] member to the mirror-service_container:mirror-service Mirror Service.

Space Browser

The Space Browser displays the Mirror Space configuration in the Cluster View in a special way. When viewing a cluster that uses a Mirror Service, the Space Browser will monitor the replication status between the different cluster nodes as well as the replication status between the cluster nodes and the Mirror service. This allows you to provision and track failures or network disruptions.