com.sleepycat.je.rep
Class ReplicatedEnvironment

java.lang.Object
  com.sleepycat.je.Environment
      com.sleepycat.je.rep.ReplicatedEnvironment

public class ReplicatedEnvironment
extends Environment

A replicated database environment that is a node in a replication group. Please read the Berkeley DB JE High Availability Overview for an introduction to basic concepts and key terminology.

Berkeley DB JE High Availability (JE HA) is a replicated, embedded database management system which provides fast, reliable, and scalable data management. JE HA enables replication of an environment across a Replication Group. A ReplicatedEnvironment is a single node in the replication group.

ReplicatedEnvironment extends Environment. All database operations are executed in the same fashion in both replicated and non replicated applications, using Environment methods. A ReplicatedEnvironment must be transactional. All databases created in the replicated environment must be transactional as well.

ReplicatedEnvironment handles are analogous to Environment handles. A replicated environment handle is a ReplicatedEnvironment instance; multiple ReplicatedEnvironment instances may be created for the same physical directory. In other words, more than one ReplicatedEnvironment handle may be open at a time for a given environment.

A ReplicatedEnvironment joins its replication group when it is instantiated. When the constructor returns, the node will have established contact with the other members of the group and will be ready to service operations. The life cycle overview is useful for understanding replication group creation.

The membership of a replication group is dynamically defined. The group comes into being when ReplicatedEnvironments that are configured as members of a group are created and discover each other. ReplicatedEnvironments are identified by a group name, a node name, and a hostname:port value. Membership information is stored in an internal, replicated database available to all nodes.

To start a node and join a group, instantiate a ReplicatedEnvironment. The very first instantiation of a node differs slightly from all future instantiations. A brand new, empty node does not yet have access to the membership database, so it must discover the group with with the aid of a helper node, which is a fellow member. If this is the very first node of the entire group, there is no available helper. Instead, the helper host address to use is the node's own address. The example below takes the simple approach of creating a replication group by starting up a node that will act as the first master, though it is not necessary to follow this order. Configuring Replicated Environments describes group startup in greater detail.

To create the the master node in a brand new group, instantiate a ReplicatedEnvironment this way:

 EnvironmentConfig envConfig = new EnvironmentConfig();
 envConfig.setAllowCreate(true);
 envConfig.setTransactional(true);

 // Identify the node
 ReplicationConfig repConfig = new ReplicationConfig();
 repConfig.setGroupName("PlanetaryRepGroup");
 repConfig.setNodeName("Mercury");
 repConfig.setNodeHostPort("mercury.acme.com:5001");

 // This is the first node, so its helper is itself
 repConfig.setHelperHosts("mercury.acme.com:5001");

 ReplicatedEnvironment repEnv =
     new ReplicatedEnvironment(envHome, repConfig, envConfig);
 

To create a new node when there are other existing group members, set a helper address which points to an existing node in the group. A simple way to bring up a new group is to "chain" the new nodes by having the helpers reference a previously created node.

 EnvironmentConfig envConfig = new EnvironmentConfig();
 envConfig.setAllowCreate(true);
 envConfig.setTransactional(true);

 // Identify the node
 ReplicationConfig repConfig = 
     new ReplicationConfig("PlanetaryRepGroup", "Jupiter", "jupiter.acme.com:5002");

 // Use the node at mercury.acme.com:5001 as a helper to find the rest
 // of the group.
 repConfig.setHelperHosts("mercury.acme.com:5001");

 ReplicatedEnvironment repEnv =
     new ReplicatedEnvironment(envHome, repConfig, envConfig);
 

In these examples, node Mercury was configured as its own helper, and becomes the first master. The next nodes were configured to use Mercury as their helper, and became replicas. It is also possible to start these in reverse order, bringing mercury up last. In that case, the earlier nodes will block until a helper is awake and can service their requests for group metadata.

Creating a ReplicatedEnvironment for an existing environment requires less configuration. The call to EnvironmentConfig.setAllowCreate() is eliminated to guard against the unintentional creation of a new environment. Also, there is no need to set a helper host address, because the environment exists and has access to the shared, persistent membership information.

 EnvironmentConfig envConfig = new EnvironmentConfig();
 envConfig.setTransactional(true);
 ReplicationConfig repConfig = 
     new ReplicationConfig("PlanetaryRepGroup", "Mercury", "mercury.acme.com:5001");

 ReplicatedEnvironment repEnv =
     new ReplicatedEnvironment(envHome, repConfig, envConfig);
 

See ReplicationGroupAdmin for information on how to remove nodes from the replication group.

ReplicatedEnvironment properties can be set via the the <environmentHome>/je.properties file, just like Environment properties. They follow the same property value precedence rules.

A replicated environment directory can only be accessed by a read write ReplicatedEnvironment handle or a read only Environment handle. In the current release, there is an additional restriction that a read only Environment is only permitted when the directory is not also accessed from a different process by a read/write ReplicatedEnvironment. If a read/write ReplicatedEnvironment and a read only Environment from two different processes concurrently access an environment directory, there is the small possibility that the read only Environment may see see exceptions thrown about an inconsistent log if the ReplicatedEnvironment executes certain kinds of failover. There is no problem if the Environment and ReplicatedEnvironment are in the same process, or are not concurrent.

JE HA prohibits opening a replicated environment directory with a read/write Environment handle, because from the group's perspective, unreplicated updates to a single node would cause data inconsistency. To use an existing, non-replicated environment to bootstrap a replication group, use DbEnableReplication to do a one time conversion of the directory.

All other database objects, such as Database or Cursor (when using the Base API) or EntityStore or PrimaryIndex (when using the Direct Persistence Layer) should be created, used and closed before calling close().

Since:

4.0

See Also:

Environment, Replication First Steps

Nested Class Summary

static class

ReplicatedEnvironment.State The replication node state determines the operations that the application can perform against its replicated environment.

Constructor Summary

ReplicatedEnvironment(File envHome, ReplicationConfig repConfig, EnvironmentConfig envConfig)
A convenience constructor that defaults the replica consistency policy and the initial election policy to be used.

ReplicatedEnvironment(File envHome, ReplicationConfig repConfig, EnvironmentConfig envConfig, ReplicaConsistencyPolicy consistencyPolicy, QuorumPolicy initialElectionPolicy)
Creates a replicated environment handle and starts participating in the replication group as either a Master or a Replica.

Method Summary

void	close() Close this ReplicatedEnvironment and release any resources used by the handle.
ReplicationGroup	getGroup() Returns a description of the replication group as known by this node.
String	getNodeName() Returns the unique name used to identify this replicated environment.
ReplicationConfig	getRepConfig() Return the replication configuration that has been used to create this handle.
ReplicationMutableConfig	getRepMutableConfig()
ReplicatedEnvironmentStats	getRepStats(StatsConfig config) Returns statistics associated with this environment.
ReplicatedEnvironment.State	getState() Returns the current state of the node associated with this replication environment.
StateChangeListener	getStateChangeListener() Returns the listener used to receive asynchronous replication node state change events.
void	setRepMutableConfig(ReplicationMutableConfig mutableConfig)
void	setStateChangeListener(StateChangeListener listener) Sets the listener used to receive asynchronous replication node state change events.
void	shutdownGroup(long replicaShutdownTimeout, TimeUnit unit) Closes this handle and shuts down the Replication Group by forcing all active Replicas to exit.

Methods inherited from class com.sleepycat.je.Environment

beginTransaction, checkpoint, cleanLog, compress, evictMemory, getConfig, getDatabaseNames, getHome, getLockStats, getMutableConfig, getStats, getThreadTransaction, getTransactionStats, isValid, openDatabase, openSecondaryDatabase, removeDatabase, renameDatabase, setMutableConfig, setThreadTransaction, sync, truncateDatabase, verify

Methods inherited from class java.lang.Object

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

Constructor Detail

ReplicatedEnvironment

public ReplicatedEnvironment(File envHome,
                             ReplicationConfig repConfig,
                             EnvironmentConfig envConfig,
                             ReplicaConsistencyPolicy consistencyPolicy,
                             QuorumPolicy initialElectionPolicy)
                      throws EnvironmentNotFoundException,
                             EnvironmentLockedException,
                             InsufficientLogException,
                             ReplicaConsistencyException,
                             IllegalArgumentException

Creates a replicated environment handle and starts participating in the replication group as either a Master or a Replica. The node's state is determined when it joins the group, and mastership is not preconfigured. If the group has no current master, creation of a handle will trigger an election to determine whether this node is a Master or a Replica.

If the node participates as a Master, the constructor will return after a sufficient number of Replicas, in accordance with the initialElectionPolicy argument, have established contact with the Master.

If the node participates as a Replica, it will become consistent in accordance with the consistencyPolicy argument before returning from the constructor.

A brand new node will always join an existing group as a Replica, unless it is the very first node that is creating the group. In that case it joins as the Master of the newly formed singleton group. A brand new node must always specify one or more active helper nodes via the ReplicationConfig.setHelperHosts(String) method or via the the <environment home>/je.properties file. If this is the very first member of a nascent group, it must specify just itself as the helper.

There are special considerations to keep in mind when a replication group is started and elections are first held to determine a master. The default QuorumPolicy.SIMPLE_MAJORITY calls for a simple majority vote. If the group members were previously created and populated, the default election policy may result in the election of a master that may not have the most up to date copy of the environment. This could happen if the best qualified node is slow to start up; it's possible that by the time it's ready to participate in an election, the election has already have completed with a simple majority.

To avoid this possibility, the method has a parameter initialElectionPolicy, which can be used to specify QuorumPolicy.ALL, which will cause the elections to wait until all nodes can vote. By ensuring that all the nodes can vote, the best possible node is chosen to be the master at group startup.

Note that it is the application's responsibility to ensure that all nodes coordinate their choice of initialElectionPolicy so that the very first elections held when a group is brought up use the same value for this parameter. This parameter is only used for the first election. After the first election has been held and the group is functioning, subsequent elections do not require participation of all the nodes. A simple majority is sufficient to elect the node with the most up to date environment as the master.

Parameters:

envHome - The environment's home directory.

repConfig - replication configurations. If null, the default replication configurations are used.

envConfig - environment configurations for this node. If null, the default environment configurations are used.

consistencyPolicy - the consistencyPolicy used by the Replica at startup to make its environment current with respect to the master. This differs from the consistency policy specified ReplicationConfig.setConsistencyPolicy(com.sleepycat.je.ReplicaConsistencyPolicy) because it is used only at construction, when the node joins the group for the first time. The consistency oolicy set in ReplicationConfig is used any time a policy is used after node startup, such as at transaction begins.

initialElectionPolicy - the policy to use when holding the initial election.

Throws:

RestartRequiredException

ReplicaConsistencyException - if it is a Replica and cannot satisfy the specified consistency policy within the joinGroupTimeout period.

UnknownMasterException - if the node cannot join the group in the time period specified by the ReplicationConfig.ENV_SETUP_TIMEOUT property.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

EnvironmentLockedException - when an environment cannot be opened for write access because another process has the same environment open for write access. Warning: This exception should be handled when an environment is opened by more than one process.

VersionMismatchException - when the existing log is not compatible with the version of JE that is running. This occurs when a later version of JE was used to create the log. Warning: This exception should be handled when more than one version of JE may be used to access an environment.

UnsupportedOperationException - if the environment exists and has not been enabled for replication.

IllegalArgumentException - if an invalid parameter is specified, for example, an invalid EnvironmentConfig parameter.

EnvironmentNotFoundException

InsufficientLogException

ReplicatedEnvironment

public ReplicatedEnvironment(File envHome,
                             ReplicationConfig repConfig,
                             EnvironmentConfig envConfig)
                      throws EnvironmentNotFoundException,
                             EnvironmentLockedException,
                             ReplicaConsistencyException,
                             InsufficientLogException,
                             RollbackException,
                             IllegalArgumentException

A convenience constructor that defaults the replica consistency policy and the initial election policy to be used.

The default replica consistency policy results in the replica being consistent with the master as of the time the handle was is created.

The default initial election policy is QuorumPolicy.SIMPLE_MAJORITY

Throws:

RestartRequiredException

ReplicaConsistencyException - if it is a Replica and cannot satisfy the default consistency policy within the joinGroupTimeout period.

UnknownMasterException - if the node cannot join the group in the time period specified by the ReplicationConfig.ENV_SETUP_TIMEOUT property.

EnvironmentLockedException - when an environment cannot be opened for write access because another process has the same environment open for write access. Warning: This exception should be handled when an environment is opened by more than one process.

VersionMismatchException - when the existing log is not compatible with the version of JE that is running. This occurs when a later version of JE was used to create the log. Warning: This exception should be handled when more than one version of JE may be used to access an environment.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

UnsupportedOperationException - if the environment exists and has not been enabled for replication.

IllegalArgumentException - if an invalid parameter is specified, for example, an invalid EnvironmentConfig parameter.

EnvironmentNotFoundException

InsufficientLogException

RollbackException

See Also:

ReplicatedEnvironment(File, ReplicationConfig, EnvironmentConfig, ReplicaConsistencyPolicy, QuorumPolicy)

Method Detail

getNodeName

public String getNodeName()

Returns the unique name used to identify this replicated environment.

Returns:

the node name

See Also:

ReplicationConfig.setNodeName(java.lang.String)

getState

public ReplicatedEnvironment.State getState()
                                     throws DatabaseException

Returns the current state of the node associated with this replication environment. See ReplicatedEnvironment.State for a desciption of node states.

If the caller's intent is to track the state of the node, StateChangeListener may be a more convenient and efficient approach, rather than using getState() directly.

Returns:

the current replication state associated with this node

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

getGroup

public ReplicationGroup getGroup()
                          throws DatabaseException

Returns a description of the replication group as known by this node. The replicated group metadata is stored in a replicated database and updates are propagated by the current master node to all replicas. If this node is not the master, it is possible for its description of the group to be out of date.

Returns:

the group description

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

close

public void close()
           throws DatabaseException

Close this ReplicatedEnvironment and release any resources used by the handle.

When the last handle is closed, allocated resources are freed, and daemon threads are stopped, even if they are performing work. The node ceases participation in the replication group. If the node was currently the master, the rest of the group will hold an election. If a quorum of nodes can participate in the election, a new master will be chosen.

The ReplicatedEnvironment should not be closed while any other type of handle that refers to it is not yet closed. For example, the ReplicatedEnvironment should not be close while there are open Database instances, or or while transactions in the environment have not yet committed or aborted. Specifically, this includes Database, Cursor and Transaction handles.

Overrides:

close in class Environment

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException

setStateChangeListener

public void setStateChangeListener(StateChangeListener listener)
                            throws DatabaseException

Sets the listener used to receive asynchronous replication node state change events. Note that there is one listener per replication node, not one per handle. Invoking this method replaces the previous Listener. Invoking this method typically results in an immediate callback to the application via the StateChangeListener.stateChange(com.sleepycat.je.rep.StateChangeEvent) method, so that the application is made aware of the existing state of the node at the time StateChangeListener is first established.

Parameters:

listener - the state change listener.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

getStateChangeListener

public StateChangeListener getStateChangeListener()
                                           throws DatabaseException

Returns the listener used to receive asynchronous replication node state change events. A StateChangeListener provides the replication application with an asynchronous mechanism for tracking the State of the replicated environment.

Note that there is one listener per replication node, not one per ReplicatedEnvironment handle.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

setRepMutableConfig

public void setRepMutableConfig(ReplicationMutableConfig mutableConfig)
                         throws DatabaseException

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

getRepMutableConfig

public ReplicationMutableConfig getRepMutableConfig()
                                             throws DatabaseException

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

getRepConfig

public ReplicationConfig getRepConfig()
                               throws DatabaseException

Return the replication configuration that has been used to create this handle. This is derived from the original configuration argument, after cloning a copy to keep it distinct from the user's instance, applying je.properties settings, and validating against the underlying node.

Returns:

this handle's configuration.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

getRepStats

public ReplicatedEnvironmentStats getRepStats(StatsConfig config)
                                       throws DatabaseException

Returns statistics associated with this environment. See ReplicatedEnvironmentStats for the kind of information available.

Parameters:

config - is used to specify attributes such as whether the stats should be cleared, whether the complete set of stats should be obtained, etc.

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if this handle or the underlying environment has already been closed.

DatabaseException

shutdownGroup

public void shutdownGroup(long replicaShutdownTimeout,
                          TimeUnit unit)
                   throws IllegalStateException

Closes this handle and shuts down the Replication Group by forcing all active Replicas to exit.

This method must be invoked on the node that's currently the Master after all other outstanding handles have been closed.

The Master waits for all active Replicas to catch up so that they have a current set of logs, and then shuts them down. The Master will wait for a maximum of replicaShutdownTimeout for a Replica to catch up. If the Replica has not caught up in this time period it will force the Replica to shut down before it is completely caught up. A negative or zero replicaShutdownTimeout value will result in an immediate shutdown without waiting for lagging Replicas to catch up. Nodes that are currently inactive cannot be contacted by the Master, as a consequence, their state is not impacted by the shutdown.

The shutdown operation will close this handle on the Master node. The environments on Replica nodes will be invalidated, and attempts to use those handles will result in a GroupShutdownException being thrown. The application is responsible for closing the remaining handles on the Replica.

Parameters:

replicaShutdownTimeout - the maximum amount of time the Master waits for a Replica to shutdown.

unit - the time unit associated with the replicaShutdownTimeout

Throws:

IllegalStateException - if the method is invoked on a node that's not currently the Master, or there are other open handles to this Environment.