Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 could not determine a Master.
    `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 `je.rep.group.joinGroupTimeout 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2004-2010 Oracle. All rights reserved.