com.continuent.tungsten.replicator.management
Interface OpenReplicatorManagerMBean

All Known Implementing Classes:

OpenReplicatorManager

public interface OpenReplicatorManagerMBean

Replicator Manager MBean interface definition. This contains all replicator management functions.

Version:

1.0

Author:

Teemu Ollakka

Field Summary

static int	signalConfigured
static int	signalConsistencyFail
static int	signalError
static int	signalOfflineReached
static int	signalRestored
static int	signalShutdown
static int	signalSynced

Method Summary

java.lang.String	backup(java.lang.String backupAgentName, java.lang.String storageAgentName, long timeout) Spawns a backup of the database and optionally waits for completion.
java.util.Map<java.lang.String,java.lang.String>	capabilities() Gets the replicator capabilities.
void	clearDynamicProperties() Clears all dynamic properties.
void	configure(java.util.Map<java.lang.String,java.lang.String> props) Run configuration on the replicator.
int	consistencyCheck(java.lang.String method, java.lang.String schemaName, java.lang.String tableName, int rowOffset, int rowLimit) Initiates consistency check transaction on a given table.
DynamicMBeanHelper	createHelper() Returns a helper that supplies MBean metadata.
java.lang.String	flush(long timeout) Implements a flush operation to synchronize the state of the database with the transaction history log and return the sequence number of the log at the point where the database is synchronized.
java.util.List<java.util.Map<java.lang.String,java.lang.String>>	getClients() Returns clients (slaves) of this server.
java.lang.String	getClusterName() Gets the cluster name for this replication service
java.util.Map<java.lang.String,java.lang.String>	getDynamicProperties() Returns a map instance containing currently set dynamic properties, if any.
java.lang.Object	getExtensionMBean(java.lang.String name) Returns the JMX API for a named extension.
java.lang.String	getMasterConnectUri() Returns the master remote URI to which this replicator connects when operating as a slave.stop
int	getMasterListenPort() Returns the port on which the replicator will listen when it's a master.
java.lang.String	getMasterListenUri() Returns the URI on which this master listens when operating as a slave.
java.lang.String	getMaxSeqNo() Returns the highest applied sequence number in the local transaction history log or -1 if log is not operating.
java.lang.String[]	getMinMaxSeqNo() Returns the lowest and the highest sequence numbers in the local transaction history log or -1 if log is not operating.
java.lang.String	getMinSeqNo() Returns the lowest sequence number in the local transaction history log or -1 if log is not operating.
java.lang.String	getPendingError() Returns description of last error if we are in OFFLINE:ERROR state or null if no error is pending.
java.lang.String	getPendingExceptionMessage() Returns message from exception that provoked the last error
java.lang.String	getRole() Returns the current replicator role.
java.lang.String	getServiceName() Gets the service name for this replication service
java.lang.String	getSimpleServiceName() Gets the simple name for this replication service
java.lang.String	getSiteName() Gets the site name for this replication service
java.lang.String	getSourceId() Returns current instance unique source identifier.
java.lang.String	getState() Returns the current replicator state.
TungstenProperties	getStatus() Deprecated. Use getStatus()
java.lang.Boolean	getUseSSLConnection() Returns true if the Replicator uses SSL connections.
java.lang.String	getVersion() Returns the replicator product version.
void	heartbeat(java.util.Map<java.lang.String,java.lang.String> props) Inserts a heartbeat event into the replicator transaction history.
boolean	isAlive() Returns true so that clients can confirm connection liveness.
java.util.List<java.lang.String>	listExtensionMBeans() Returns a list of the names of currently defined extension MBeans.
void	offline() Puts the replicator into the offline state immediately without clean-up, returning once the replicator is offline.
void	offlineDeferred(java.util.Map<java.lang.String,java.lang.String> controlParams) Issues a request to go offline at a particular event or sequence number.
void	online() Puts the replicator into the online state using defaults for all control parameters.
void	online2(java.util.Map<java.lang.String,java.lang.String> controlParams) Puts the replicator into the online state.
java.util.Map<java.lang.String,java.lang.String>	properties(java.lang.String key) Returns a map instance containing currently set properties, if any.
boolean	provision(java.lang.String donorUri, long timeout) Provisions a database from another copy and optionally waits for completion.
int	purge(java.util.Map<java.lang.String,java.lang.String> controlParams) Attempts to kill all non-replication logins on the DBMS server.
java.lang.String	restore(java.lang.String uri, long timeout) Spawns a restore of the database and optionally waits for completion.
void	setRole(java.lang.String role, java.lang.String uri) Sets replicator role.
void	signal(int signal, java.lang.String msg) Notification signaling methods.
void	start(boolean forceOffline) Starts the replicator service, which spawns all threads and underlying components necessary to perform replication.
java.util.Map<java.lang.String,java.lang.String>	status() Returns the detailed, current status information from the replicator.
java.util.List<java.util.Map<java.lang.String,java.lang.String>>	statusList(java.lang.String name) Returns a list of status instances for a particular list of items.
void	stop() Stops the OpenReplicatorManager
boolean	waitForAppliedSequenceNumber(java.lang.String sequenceNo, long timeout) Wait for a particular event to be applied on the slave.
boolean	waitForState(java.lang.String state, long timeout) Waits for the replicator to attain a specific state, such as "SLAVE".

Field Detail

signalOfflineReached

static final int signalOfflineReached

See Also:

Constant Field Values

signalShutdown

static final int signalShutdown

See Also:

Constant Field Values

signalConfigured

static final int signalConfigured

See Also:

Constant Field Values

signalSynced

static final int signalSynced

See Also:

Constant Field Values

signalRestored

static final int signalRestored

See Also:

Constant Field Values

signalConsistencyFail

static final int signalConsistencyFail

See Also:

Constant Field Values

signalError

static final int signalError

See Also:

Constant Field Values

Method Detail

isAlive

boolean isAlive()

Returns true so that clients can confirm connection liveness.

Returns:

true if the service is up and running, false otherwise

getSiteName

java.lang.String getSiteName()

Gets the site name for this replication service

Returns:

the site name as a string

getClusterName

java.lang.String getClusterName()

Gets the cluster name for this replication service

Returns:

the cluster name as a string

getServiceName

java.lang.String getServiceName()

Gets the service name for this replication service

Returns:

the service name as a string

getSimpleServiceName

java.lang.String getSimpleServiceName()

Gets the simple name for this replication service

Returns:

the simple name of this service as a string

getVersion

java.lang.String getVersion()

Returns the replicator product version.

Returns:

the version number as a string

getSourceId

java.lang.String getSourceId()

Returns current instance unique source identifier.

Returns:

the source identifier as a string

getRole

java.lang.String getRole()

Returns the current replicator role.

Returns:

the role as a string

getMasterConnectUri

java.lang.String getMasterConnectUri()

Returns the master remote URI to which this replicator connects when operating as a slave.stop

getMasterListenUri

java.lang.String getMasterListenUri()

Returns the URI on which this master listens when operating as a slave.

getUseSSLConnection

java.lang.Boolean getUseSSLConnection()
                                      throws java.net.URISyntaxException

Returns true if the Replicator uses SSL connections.

Throws:

java.net.URISyntaxException

getMasterListenPort

int getMasterListenPort()

Returns the port on which the replicator will listen when it's a master.

getClients

java.util.List<java.util.Map<java.lang.String,java.lang.String>> getClients()
                                                                            throws java.lang.Exception

Returns clients (slaves) of this server.

Throws:

java.lang.Exception

getState

java.lang.String getState()

Returns the current replicator state.

getPendingError

java.lang.String getPendingError()

Returns description of last error if we are in OFFLINE:ERROR state or null if no error is pending.

getPendingExceptionMessage

java.lang.String getPendingExceptionMessage()

Returns message from exception that provoked the last error

getMaxSeqNo

java.lang.String getMaxSeqNo()
                             throws java.lang.Exception

Returns the highest applied sequence number in the local transaction history log or -1 if log is not operating.

Throws:

java.lang.Exception

getMinSeqNo

java.lang.String getMinSeqNo()
                             throws java.lang.Exception

Returns the lowest sequence number in the local transaction history log or -1 if log is not operating.

Throws:

java.lang.Exception

getMinMaxSeqNo

java.lang.String[] getMinMaxSeqNo()
                                  throws java.lang.Exception

Returns the lowest and the highest sequence numbers in the local transaction history log or -1 if log is not operating.

Throws:

java.lang.Exception

online2

void online2(java.util.Map<java.lang.String,java.lang.String> controlParams)
             throws java.lang.Exception

Puts the replicator into the online state. This call returns when the request to go online has been accepted. The replicator must be in thstope OFFLINE state for this call to be processed.

The online operation accepts name-value control parameters that allow users to control replicator behavior when going online.

stop

Name	Description	Default
initEventId	Sets initial native event ID at which to start extraction, overriding value from the last event extracted	Replication starts at either last event ID extracted or, if there is none, the current event ID
skipApplyEvents	Number of events to skip applying at startup	0
toEventId	Replicate up to the indicated event ID	None
toSeqno	Replicate up to the indicated sequence number	None

Due to the fact that the replicator may need to synchronize with a master it may be some time before the replicator actually reaches the online state. Use the waitForState(String, long) call to wait synchronously for the replicator to go fully online.

Parameters:

controlParams - 0 or more control parameters expressed as name-value pairs

Throws:

java.lang.Exception

online

void online()
            throws java.lang.Exception

Puts the replicator into the online state using defaults for all control parameters.

Throws:

java.lang.Exception

offlineDeferred

void offlineDeferred(java.util.Map<java.lang.String,java.lang.String> controlParams)
                     throws java.lang.Exception

Issues a request to go offline at a particular event or sequence number. The replicator must be in the ONLINE state for this call to be processed.

The offline operation accepts name-value control parameters that allow users to control replicator behavior.

Name	Description	Parameter	Default
atEventId	Go offline at the requested event	An event ID in native format	None
atHeartbeat	Go offline at the next heartbeat event.	A heartbeat name or * to select any heartbeat	*
atSeqno	Go offline at the indicated sequence number	A valid sequence number	None
atTransaction	Go offline cleanly at the next transaction. This is the best way to take a replicator offline as it ensures the replicator can reload backups when parallel apply is in effect or make change to parallel apply parameters	Insert any value	None
atTimestamp	Go offline cleanly at the next transaction. This is the best way to take a replicator offline as it ensures the replicator can reload backups when parallel apply is in effect or make change to parallel apply parameters	A timestamp String in yyyy-MM-dd HH:mm:ss format	None

Parameters:

controlParams - 0 or more control parameters expressed as name-value pairs

Throws:

java.lang.Exception

offline

void offline()
             throws java.lang.Exception

Puts the replicator into the offline state immediately without clean-up, returning once the replicator is offline. The replicator must be in the ONLINE or GOING-ONLINE state for this call to be processed.

This call is hazardous on slaves using parallel apply. It does not do a clean offline operation, which means that it is unsafe for doing failover operations, creating a backup that can restore when using different numbers of parallel apply channels or for changing any parameters associated with parallel apply. You should use offlineDeferred for clean shutdown.

Throws:

java.lang.Exception

flush

java.lang.String flush(long timeout)
                       throws java.lang.Exception

Implements a flush operation to synchronize the state of the database with the transaction history log and return the sequence number of the log at the point where the database is synchronized. The replicator must be in the ONLINE:MASTER state for this call to be processed. This call is used to implement safe failover.

Parameters:

timeout - Number of seconds to wait. 0 is indefinite.

Returns:

The sequence number at which the log is synchronized

Throws:

java.lang.Exception - Thrown if we timeout or are canceled

purge

int purge(java.util.Map<java.lang.String,java.lang.String> controlParams)
          throws java.lang.Exception

Attempts to kill all non-replication logins on the DBMS server. May be called prior to flush() to ensure that all application activity stops prior to a failover. This avoids problems with blocked or long-running transactions that commit after failover starts. This operation works in both ONLINE and OFFLINE states so that it can be used to clear transactions during unplanned as well as planned failover.

The following control parameters are accepted:

• timeout - Number of seconds to wait for kill operations to complete

Parameters:

controlParams - 0 or more control parameters expressed as name-value pairs

Returns:

Number of sessions killed

Throws:

java.lang.Exception - Thrown if we timeout or are canceled

getStatus

@Deprecated
TungstenProperties getStatus()
                             throws java.lang.Exception

Deprecated. Use getStatus()

Throws:

java.lang.Exception

status

java.util.Map<java.lang.String,java.lang.String> status()
                                                        throws java.lang.Exception

Returns the detailed, current status information from the replicator.

Returns:

detailed status information as a TungstenProperties instance

Throws:

java.lang.Exception

statusList

java.util.List<java.util.Map<java.lang.String,java.lang.String>> statusList(java.lang.String name)
                                                                            throws java.lang.Exception

Returns a list of status instances for a particular list of items.

Parameters:

name - Name of the status list. 'tasks' is supported by the native Tungsten replicator plugin.

Returns:

List of TungstenProperties instances containing task status

Throws:

java.lang.Exception

stop

void stop()
          throws java.lang.Exception

Stops the OpenReplicatorManager

Throws:

java.lang.Exception

configure

void configure(java.util.Map<java.lang.String,java.lang.String> props)
               throws java.lang.Exception

Run configuration on the replicator. The replicator must be in the OFFLINE state. If the map instance is null the Replicator will read its own properties file, whose location is defined by the System property named "replicator.properties."

Parameters:

props - A map instance or null to reread local file

Throws:

java.lang.Exception

heartbeat

void heartbeat(java.util.Map<java.lang.String,java.lang.String> props)
               throws java.lang.Exception

Inserts a heartbeat event into the replicator transaction history. The replicator manager must be in the MASTER state for this call to be successful.

Parameters:

props - A map instance containing heartbeat parameters

Throws:

java.lang.Exception

waitForState

boolean waitForState(java.lang.String state,
                     long timeout)
                     throws java.lang.Exception

Waits for the replicator to attain a specific state, such as "SLAVE". The wait time is configurable so that callers do not wait indefinitely. The wait will terminate automatically with an exception if the replicator goes into the error state (unless that is what you are waiting for).

Parameters:

state - Name of state on which to wait. This can be a parent state name--"OFFLINE" will also detect "OFFLINE:NORMAL" and "OFFLINE:ERROR".

timeout - Number of seconds to wait. 0 is indefinite.

Returns:

true if requested wait state is achieved, else false if the wait timed out

Throws:

java.lang.Exception

waitForAppliedSequenceNumber

boolean waitForAppliedSequenceNumber(java.lang.String sequenceNo,
                                     long timeout)
                                     throws java.lang.Exception

Wait for a particular event to be applied on the slave.

Parameters:

sequenceNo - Id of the event to wait for

timeout - Number of seconds to wait. 0 is indefinite.

Returns:

true if requested sequence number or greater applied, else false if the wait timed out

Throws:

java.lang.Exception - if there is a timeout or we are canceled

consistencyCheck

int consistencyCheck(java.lang.String method,
                     java.lang.String schemaName,
                     java.lang.String tableName,
                     int rowOffset,
                     int rowLimit)
                     throws java.lang.Exception

Initiates consistency check transaction on a given table.

Parameters:

method - consistency check method to use

schemaName - name of the table schema

tableName - name of the table, if null all tables in schema are checked

rowOffset - start consistency check from this row (numeration starts with 0). If negative - whole table is checked.

rowLimit - limit consistency check to that many rows. If rowOffset is negative this is ignored.

Returns:

Executed consistency check's ID.

Throws:

java.lang.Exception

backup

java.lang.String backup(java.lang.String backupAgentName,
                        java.lang.String storageAgentName,
                        long timeout)
                        throws java.lang.Exception

Spawns a backup of the database and optionally waits for completion. This command can only be run in the off-line state.

Parameters:

backupAgentName - Name of the backup agent to use or null to use the default backup

storageAgentName - Name of the storage agent to use or null to use the default storage

timeout - Number of seconds to wait. 0 is indefinite, negative means no wait.

Returns:

A URI for the backup if successful, otherwise a null if the backup is still pending

Throws:

java.lang.Exception - if there is a backup failure

restore

java.lang.String restore(java.lang.String uri,
                         long timeout)
                         throws java.lang.Exception

Spawns a restore of the database and optionally waits for completion. This command can only be run in the off-line state.

Parameters:

uri - URI of the backup to load

timeout - Number of seconds to wait. 0 is indefinite, negative means no wait.

Returns:

the URI of the restored backup if the restore is known to have completed successfully, otherwise null, which means restore is still pending

Throws:

java.lang.Exception - if there is a restore failure

provision

boolean provision(java.lang.String donorUri,
                  long timeout)
                  throws java.lang.Exception

Provisions a database from another copy and optionally waits for completion. This command can only be run from the off-line state.

Parameters:

donorUri - URI of donor replicator

timeout - Number of seconds to wait. 0 is indefinite, negative means no wait.

Returns:

true if the provision task is known to have completed successfully, otherwise false, which means provisioning is still pending

Throws:

java.lang.Exception - if there is a provisioning failure

start

void start(boolean forceOffline)
           throws java.lang.Exception

Starts the replicator service, which spawns all threads and underlying components necessary to perform replication. It is the first call to a new replication service. It also issues a call to put the replicator services online if auto_enable is set in configuration file, except if forceOffline is true.

Parameters:

forceOffline - true to prevent the replicator from putting its replication services online (if auto-enable is set to true)

Throws:

java.lang.Exception - Thrown if start-up fails. This includes failure to go online if the replicator is auto-enabled.

properties

java.util.Map<java.lang.String,java.lang.String> properties(java.lang.String key)
                                                            throws java.lang.Exception

Returns a map instance containing currently set properties, if any. This call can be issued in any replicator state.

Parameters:

key - optional key of a single property

Returns:

the current property(ies)

Throws:

java.lang.Exception

getDynamicProperties

java.util.Map<java.lang.String,java.lang.String> getDynamicProperties()
                                                                      throws java.lang.Exception

Returns a map instance containing currently set dynamic properties, if any. This call can be issued in any replicator state.

Throws:

java.lang.Exception

clearDynamicProperties

void clearDynamicProperties()
                            throws java.lang.Exception

Clears all dynamic properties. The replicator must be in the OFFLINE state when this call is issued.

Throws:

java.lang.Exception

setRole

void setRole(java.lang.String role,
             java.lang.String uri)
             throws java.lang.Exception

Sets replicator role. Not all replicators support all roles; check other documentation for details.

Parameters:

role - The new replicator role; must be 'slave', 'master', or 'standby'

uri - Optional uri to identify master or slave.

Throws:

java.lang.Exception

getExtensionMBean

java.lang.Object getExtensionMBean(java.lang.String name)
                                   throws java.lang.Exception

Returns the JMX API for a named extension.

Throws:

java.lang.Exception

listExtensionMBeans

java.util.List<java.lang.String> listExtensionMBeans()
                                                     throws java.lang.Exception

Returns a list of the names of currently defined extension MBeans.

Throws:

java.lang.Exception

createHelper

DynamicMBeanHelper createHelper()
                                throws java.lang.Exception

Returns a helper that supplies MBean metadata.

Throws:

java.lang.Exception

signal

void signal(int signal,
            java.lang.String msg)
            throws java.lang.Exception

Notification signaling methods. These sends a notification to the replicator manager. These methods are used by replicator providers, which need to signal of underlying state changes.

Parameters:

signal - one of signal* strings listed in this interface

msg - additional message passed along the signal

Throws:

java.lang.Exception

capabilities

java.util.Map<java.lang.String,java.lang.String> capabilities()
                                                              throws java.lang.Exception

Gets the replicator capabilities.

Throws:

java.lang.Exception