com.sleepycat.je.rep (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

# Package com.sleepycat.je.rep

Berkeley DB Java Edition High Availability (JE HA) enables replication of JE environments.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AppStateMonitor | A mechanism for adding application specific information when asynchronously tracking the state of a running JE HA application.
  ReplicationNode | An administrative view of a node in a replication group.
  StateChangeListener | An asynchronous mechanism for tracking the `State` of the replicated environment and choosing how to route database operations.

- Class Summary
  Class | Description
  --- | ---
  CommitPointConsistencyPolicy | A consistency policy which ensures that the environment on a Replica node is at least as current as denoted by the specified `CommitToken`.
  NetworkRestore | Obtains log files for a Replica from other members of the replication group.
  NetworkRestoreConfig | NetworkRestoreConfig defines the configuration parameters used to configure a NetworkRestore operation.
  NoConsistencyRequiredPolicy | A consistency policy that lets a transaction on a replica using this policy proceed regardless of the state of the Replica relative to the Master.
  NodeState | The current state of a replication node and the application this node is running in.
  ReplicatedEnvironment | A replicated database environment that is a node in a replication group.
  ReplicatedEnvironmentStats | Statistics for a replicated environment.
  ReplicationConfig | Specifies the immutable attributes of a replicated environment.
  ReplicationGroup | An administrative view of the collection of nodes that form the replication group.
  ReplicationMutableConfig | Specifies the attributes that may be changed after a `ReplicatedEnvironment` has been created.
  StateChangeEvent | Communicates the `state` change at a node to the StateChangeListener.
  TimeConsistencyPolicy | A consistency policy which describes the amount of time the Replica is allowed to lag the Master.

- Enum Summary
  Enum | Description
  --- | ---
  NodeType | The different types of nodes that can be in a replication group.
  QuorumPolicy | The quorum policy determine the number of nodes that must participate to pick the winner of an election, and therefore the master of the group.
  ReplicatedEnvironment.State | The replication node state determines the operations that the application can perform against its replicated environment.
  SyncupProgress | Describes the different phases of replication stream syncup that are executed when a replica starts working with a new replication group master.

- Exception Summary
  Exception | Description
  --- | ---
  DatabasePreemptedException | Thrown when attempting to use a Database handle that was forcibly closed by replication.
  GroupShutdownException | Thrown when an attempt is made to access an environment that was shutdown by the Master as a result of a call to `ReplicatedEnvironment.shutdownGroup(long, TimeUnit)`.
  InsufficientAcksException | This exception is thrown at the time of a commit in a Master, if the Master could not obtain transaction commit acknowledgments from its Replicas in accordance with the `Durability.ReplicaAckPolicy` currently in effect and within the requested timeout interval.
  InsufficientLogException | This exception indicates that the log files constituting the Environment are insufficient and cannot be used as the basis for continuing with the replication stream provided by the current master.
  InsufficientReplicasException | Thrown by `Environment.beginTransaction(com.sleepycat.je.Transaction, com.sleepycat.je.TransactionConfig)` and `Transaction.commit()` when these operations are initiated at a Master which is not in contact with a quorum of Replicas as determined by the `Durability.ReplicaAckPolicy` that is in effect for the operation.
  LockPreemptedException | Thrown when a lock has been "stolen", or preempted, from a transaction in a replicated environment.
  LogOverwriteException | Thrown when one or more log files are modified (overwritten) as the result of a replication operation.
  MasterReplicaTransitionException | Deprecated as of JE 5.0.88 because the environment no longer needs to restart when transitioning from master to replica.
  MasterStateException | This exception indicates that the application attempted an operation that is not permitted when it is in the `ReplicatedEnvironment.State.MASTER` state.
  MasterTransferFailureException | Thrown by `ReplicatedEnvironment.transferMaster(java.util.Set<java.lang.String>, int, java.util.concurrent.TimeUnit)` if a Master Transfer operation cannot be completed within the allotted time.
  MemberNotFoundException | Thrown when an operation requires a replication group member and that member is not present in the replication group.
  ReplicaConsistencyException | This exception is thrown by a Replica to indicate it could not meet the consistency requirements as defined by the `ReplicaConsistencyPolicy` in effect for the transaction, within the allowed timeout period.
  ReplicaStateException | This exception indicates that the application attempted an operation that is not permitted when it is in the `ReplicatedEnvironment.State.REPLICA` state.
  ReplicaWriteException | This exception indicates that an update operation or transaction commit or abort was attempted while in the `ReplicatedEnvironment.State.REPLICA` state.
  RestartRequiredException | RestartRequiredException serves as the base class for all exceptions which makes it impossible for HA to proceed without some form of corrective action on the part of the user, followed by a restart of the application.
  RollbackException | This asynchronous exception indicates that a new master has been selected, this `Replica`'s log is ahead of the current `Master`, and in this case, the `Replica` was unable to rollback without a recovery.
  RollbackProhibitedException | This exception may be thrown by a Replica during the replication stream sync-up phase of startup.
  StateChangeException | Provides a synchronous mechanism for informing an application about a change in the state of the replication node.
  UnknownMasterException | Indicates that the underlying operation requires communication with a Master, but that a Master was not available.

## Package com.sleepycat.je.rep Description

Berkeley DB Java Edition High Availability (JE HA) enables replication of JE environments. JE HA is an embedded database management system designed to provide fast, reliable, and scalable data management. A JE environment is replicated across the nodes of a single read/write Master, multiple read only Replica Replication Group. JE HA is used to improve application availability, provide improved read performance, and increase data durability.

### Getting Started

The Replication Guide is invaluable for understanding the capabilities of JE HA and how best to design your replicated application.

> The Introduction covers terminology, the replication group lifecycle, and the concepts of durability and consistency. Much of the javadoc refers to the topics covered there.

> Replication API First Steps explains how to configure and start a replication group.

> Transaction Management highlights the tradeoffs that must be considered in a replicated application and provides some use cases.

In addition, the je.rep.quote example package provides three example replication applications.

### What the com.sleepycat.je.rep package contains

##### Replication control

- `ReplicatedEnvironment` is the main access point to replication.
- `ReplicationConfig` and `ReplicationMutableConfig` specify attributes of the replication system.

##### Administration

- `ReplicationNode` and `ReplicationGroup` supply administrative views of the replication system.

##### Support

- `StateChangeListener` and `StateChangeEvent` implement a Listener pattern for tracking changes in the replication system.
- `CommitPointConsistencyPolicy`, `TimeConsistencyPolicy` and `NoConsistencyPolicy` let the user control the read only replica's view of the the replicated data.
- `ReplicatedEnviromentStats` provide feedback on system execution.

### Related Packages

- com.sleepycat.je.rep.monitor lets the application track the replication system in order to do tasks such as load balancing and write request routing.
- com.sleepycat.je.rep.util provides command line and programmatic APIs for administering and starting up a replication system.

### Related Documentation

See Also:
  Replication Guide, JE HA Examples

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.