com.luciad.fusion.engine.replication

Tiling EngineClass TLfnReplication

java.lang.Object

com.luciad.fusion.engine.replication.TLfnReplication

public final class TLfnReplication
extends Object

This class allows to compare and replicate resources between two tile stores. Replication of a resource means that the data and metadata which are present on a master tile store are copied to a slave tile store. When the process is done, the resource of the slave tile store will have a state which is consistent with the state of the resources on the master.

This class represents an in-memory preview of the replication between two tile stores. For each resource, you can:

• Inspect the state of the resource on the master and the slave.
• Inspect what the resulting state will be after replicating.
• Specify whether the resource needs to be replicated or not. For example if the slave tile store has more recent data then the master tile store, you can decide not to overwrite the recent slave data with old data from the master.
• Specify which region or "area of interest" must be replicated. For example if the master tile store contains data of the whole world but the slave tile store only needs data for a certain region, you can limit the data which will be replicated to this region. Data outside this region will not be transferred to the slave. This saves disk space for the slave tile store and decreases the amount of network traffic used for replication.
  The available areas are managed by a manager which can be obtained using the getAreaOfInterestManager() method.

It is important to note that any changes you made to an instance of this class will have no effect to the tile stores until you commit the changes. This class loads all info in-memory when it is constructed. Any changes made to the created instance only affect the in-memory model. Any getter you call on the created instance will return the in-memory value. Only when you call commit(com.luciad.fusion.engine.TLfnEngineFactory) or commitAndFuse(com.luciad.fusion.engine.TLfnEngineFactory) the in-memory state will be applied to the slave tile store.

Examples

Comparing two tile stores

The following code snippet compares two tile stores and prints the id of each resource and its status. An example usage would be to show the user the state of the different resources before actually replicating the two tile stores.

 TLfnReplication replication = TLfnReplication.create(fMasterTileStore, fSlaveTileStore, fEnvironment, fClientEnvironment);

 for (String resourceID : replication.getResourceIDs()) {
   TLfnReplicationResource resource = replication.getResource(resourceID);
   TLfnReplicationResource.Status status = resource.getStatus();
   System.out.println(resourceID + ": " + status);
 }
 

Replicating two tile stores without user feedback

The following code snippet replicates two tile stores without providing any feedback to the user. This code will block until the replication is done. An example use-case would be an automated script which performs replication at fixed times without any user interaction.

 TLfnReplication replication = TLfnReplication.create(fMasterTileStore, fSlaveTileStore, fEnvironment, fClientEnvironment);
 replication.commitAndFuse(engineFactory);
 

Replicating two tile stores with user feedback

The following code snippet replicates two tile stores and prints progress information.

 TLfnReplication replication = TLfnReplication.create(fMasterTileStore, fSlaveTileStore, fEnvironment, fClientEnvironment);
 List<ALfnEngine> engines = replication.commit(engineFactory);

 for (final ALfnEngine engine : engines) {
   // Start the engine
   engine.fuse(null);
   // Report progress
   final Timer progressReporter = new Timer();
   progressReporter.scheduleAtFixedRate(new TimerTask() {
     @Override
     public void run() {
       TLfnProgress progress = engine.getProgress();
       if (progress.get() == TLfnProgress.UNKNOWN_BOUND) {
         return;
       }
       System.out.println("Resource: " + engine.getCoverageId() + " - Percentage done: " + progress.getAsFraction() * 100 + "%");
       if (engine.getStatus() == ELfnStatus.COMPLETED || engine.getStatus() == ELfnStatus.FAILED) {
         progressReporter.cancel();
       }
     }
   }, 0, 500);
 }

 // Wait for all engines to finish
 for (ALfnEngine engine : engines) {
   try {
     engine.fuse(null).get();
   } catch (InterruptedException | ExecutionException e) {
     //ignore, just continue with the next engine
     System.out.println("Engine for resource " + engine.getCoverageId() + " failed.");
   }
 }
 

Only replicating specific resources

The following code snippet illustrates how the default replication behavior can be customized. It shows how you can avoid that data which is not present on the master is removed from the slave. A possible use-case for this is a slave which needs to contain replicated resources and its own data which was fused on the slave but never present on the master.

 TLfnReplication replication = TLfnReplication.create(fMasterTileStore, fSlaveTileStore, fEnvironment, fClientEnvironment);

 for (String resourceID : replication.getResourceIDs()) {
   TLfnReplicationResource resource = replication.getResource(resourceID);
   if (resource.getStatus() == ONLY_PRESENT_ON_SLAVE) {
     resource.unmarkForReplication();
   }
 }

 replication.commitAndFuse(engineFactory);
 

Limit the replication to a certain geographical region

The following code snippet illustrates how you can limit the replication to a certain area of interest. In this example, a new area is defined and used for all resources. Consult the javadoc of the TLfnReplicationAreaOfInterestManager class and its methods for more information on how to create and work with area of interest in the context of replication.

 ILcdShape area = ... ;
 ILcdGeoReference areaReference = new TLcdGeodeticReference();

 TLfnReplication replication = TLfnReplication.create(fMasterTileStore, fSlaveTileStore, fEnvironment, fClientEnvironment);

 //create a new area of interest
 TLfnReplicationAreaOfInterestManager areaOfInterestManager = replication.getAreaOfInterestManager();
 TLfnReplicationAreaOfInterest areaOfInterest = areaOfInterestManager.add(area, areaReference, "Europe");

 //limit the replication of each resource to this area
 for (String resourceID : replication.getResourceIDs()) {
   TLfnReplicationResource resource = replication.getResource(resourceID);
   resource.setAreaOfInterest(areaOfInterest);
 }

 replication.commitAndFuse(engineFactory);
 

Note that if you ever replicated a certain resource with a certain area of interest, this class will automatically use that same area of interest for that resource if you replicate it a second time. For the above example, this means that if you replicate a second time and you want to use the same area, it is no longer needed to specify the area of interest again. By default, each resource will be configured to use the same area of interest as during the last replication. As such, it is sufficient to use the following code to replicate a second time (e.g. after data has changed on the master) re-using the area of interest used in the first snippet.

 TLfnReplication replication = TLfnReplication.create(fMasterTileStore, fSlaveTileStore, fEnvironment, fClientEnvironment);
 replication.commitAndFuse(engineFactory);
 

If you want to replicate data from another area of interest, you need to configure a new area of interest for the resource (see Resource#setAreaOfInterest) or update the area of interest instance (see AreaOfInterest#setShape).

Limitations

Replication is only supported between Fusion servers running V2015.0 or higher.

Since:

2015.0

Method Summary

Modifier and Type	Method and Description
List<ALfnEngine>	commit(TLfnEngineFactory aEngineFactory) Method which commits the changes which were made in-memory to the slave tile store.
void	commitAndFuse(TLfnEngineFactory aEngineFactory) Method which commits the changes which were made in-memory to the slave tile store.
static TLfnReplication	create(ALfnTileStore aMasterTileStore, ALfnTileStore aSlaveTileStore, ALfnEnvironment aEnvironment, ALfnClientEnvironment aClientEnvironment) Creates a new replication preview instance.
TLfnReplicationAreaOfInterestManager	getAreaOfInterestManager() Returns the area of interest manager associated to this replication session.
ALfnTileStore	getMasterTileStore() Returns the master tile store
TLfnReplicationResource	getResource(String aResourceID) Returns the replication preview for the specified resource.
Collection<String>	getResourceIDs() Returns an unmodifiable collection containing the ids of all the resources involved in this replication
ALfnTileStore	getSlaveTileStore() Returns the slave tile store

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static TLfnReplication create(ALfnTileStore aMasterTileStore,
                                     ALfnTileStore aSlaveTileStore,
                                     ALfnEnvironment aEnvironment,
                                     ALfnClientEnvironment aClientEnvironment)
                              throws TLfnServiceException,
                                     IOException

Creates a new replication preview instance.

This factory method will query both the master and slave tile store in order to be able to construct its in-memory model of the replication (see class javadoc for more info). This can be time-consuming and is done on the calling thread. This method will block until the in-memory model is ready.

Parameters:

aMasterTileStore - The master tile store.

aSlaveTileStore - The slave tile store

aEnvironment - The Fusion environment

aClientEnvironment - The Fusion client environment

Throws:

TLfnServiceException - in case of a service processing failure or conflict

IOException - in case of an I/O failure

getMasterTileStore

public ALfnTileStore getMasterTileStore()

Returns the master tile store

Returns:

the master tile store

getSlaveTileStore

public ALfnTileStore getSlaveTileStore()

Returns the slave tile store

Returns:

the slave tile store

getResource

public TLfnReplicationResource getResource(String aResourceID)

Returns the replication preview for the specified resource.

Parameters:

aResourceID - The id of the resource. Must be one of the ids from getResourceIDs()

Returns:

the replication preview for the specified resource.

getResourceIDs

public Collection<String> getResourceIDs()

Returns an unmodifiable collection containing the ids of all the resources involved in this replication

Returns:

an unmodifiable collection containing the ids of all the resources involved in this replication

commitAndFuse

public void commitAndFuse(TLfnEngineFactory aEngineFactory)
                   throws IOException,
                          TLfnServiceException

Method which commits the changes which were made in-memory to the slave tile store. It will update the metadata in the slave tile store, and then create and run engines to replicate the actual data.

This method is blocking and will only return when all engines have run. This method does not offer any control over the order in which the different engines are run, nor does it offer any feedback mechanism (e.g. progress notifications). You should use the commit(com.luciad.fusion.engine.TLfnEngineFactory) method if you want such functionality. That method offers access to the engines which allows to start them in any order you want, or to request the progress of each engine. Consult the class javadoc for an example.

Warning: once this method is called, it is no longer possible to use this instance. Calling a method on this instance afterwards will throw exceptions.

Parameters:

aEngineFactory - An engine factory, used to create the engine instances which will perform the replication of the data.

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure or conflict

See Also:

commit(com.luciad.fusion.engine.TLfnEngineFactory)

commit

public List<ALfnEngine> commit(TLfnEngineFactory aEngineFactory)
                        throws IOException,
                               TLfnServiceException

Method which commits the changes which were made in-memory to the slave tile store. It will update the metadata in the slave tile store, and return engines for each of the coverages which must be replicated.

When this method returns, the metadata of the resources on the slave will be updated. However, the actual data must still be replicated. This can be done by running the engines returned by this method. Consult the class javadoc for an example.

Warning: once this method is called, it is no longer possible to use this instance. Calling a method on this instance afterwards will throw exceptions.

Parameters:

aEngineFactory - An engine factory, used to create the engine instances which will perform the replication of the data.

Returns:

a list of ALfnEngine instances which will perform the replication of the actual data.

Throws:

IOException - in case of an I/O failure

TLfnServiceException - in case of a service processing failure or conflict

See Also:

commitAndFuse(TLfnEngineFactory)

getAreaOfInterestManager

public TLfnReplicationAreaOfInterestManager getAreaOfInterestManager()

Returns the area of interest manager associated to this replication session.

Warning: once the commit(TLfnEngineFactory) or the commitAndFuse(TLfnEngineFactory) method has been called, you can no longer use the returned TLfnReplicationAreaOfInterestManager.

Returns:

the area of interest manager associated to this replication session.