Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.db.SlaveDatabase

Modifier and Type	Class and Description
private class	SlaveDatabase.SlaveDatabaseBootThread Thread that boots the slave database.

Modifier and Type	Field and Description
private volatile StandardException	bootException Set by the database boot thread if it fails before slave mode has been started properly (i.e., if inBoot is true).
private String	dbname
private volatile boolean	inBoot True until this database has been successfully booted.
private volatile boolean	inReplicationSlaveMode True until SlaveDatabaseBootThread has successfully booted the database.
private volatile boolean	shutdownInitiated
private volatile SlaveFactory	slaveFac

Access	Constructor and Description
public	SlaveDatabase()

Method Summary

Modifier and Type	Method and Description
public void	boot(boolean True if the database should be created create, Properties Configuration properties startParams) Overrides org.apache.derby.impl.db.BasicDatabase.boot. Implements org.apache.derby.iapi.services.monitor.ModuleControl.boot. Boot this module with the given properties.
private void	bootBasicDatabase(boolean create, Properties params)
public boolean	Returns: true if the database is updatable (not read-only) and replication slave mode is specified in startParams canSupport(Properties The properties used to decide if SlaveDatabase is the correct implementation of Database for the database to be booted. startParams) Overrides org.apache.derby.impl.db.BasicDatabase.canSupport. Implements org.apache.derby.iapi.services.monitor.ModuleSupportable.canSupport. Determines whether this Database implementation should be used to boot the database.
public void	failover(String the replication database that is being failed over. dbname) Overrides org.apache.derby.impl.db.BasicDatabase.failover. Implements org.apache.derby.iapi.db.Database.failover. Start failover for the given database.
private static Object	findServiceModule(final Object serviceModule, final String factoryInterface) Hides org.apache.derby.impl.db.BasicDatabase.findServiceModule. Must be private so that user code can't call this entry point.
public AuthenticationService	getAuthenticationService() Overrides org.apache.derby.impl.db.BasicDatabase.getAuthenticationService. Implements org.apache.derby.iapi.db.Database.getAuthenticationService. This method returns the authentication service handle for the database.
private static ContextService	getContextService() Hides org.apache.derby.impl.db.BasicDatabase.getContextService. Must be private so that user code can't call this entry point.
private void	handleShutdown(StandardException the reason why the database needs to be shutdown shutdownCause) Used to shutdown this database.
public boolean	isInSlaveMode() Overrides org.apache.derby.impl.db.BasicDatabase.isInSlaveMode. Implements org.apache.derby.iapi.db.Database.isInSlaveMode. Used to indicated whether the database is in the replication slave mode.
private boolean	Returns: true if slaveFac is set after calling this method, false otherwise isSlaveFactorySet() If slaveFac (the reference to the SlaveFactory) has not already been set, this method will try to set it by calling Monitor.findServiceModule.
public LanguageConnectionContext	setupConnection(ContextManager The context manager cm, String The UserID of the user getting the connection user, String The drda id of the connection (from network server) drdaID, String The database name dbname) Overrides org.apache.derby.impl.db.BasicDatabase.setupConnection. Implements org.apache.derby.iapi.db.Database.setupConnection. Sets up a connection to the Database, owned by the given user.
public void	stop() Overrides org.apache.derby.impl.db.BasicDatabase.stop. Implements org.apache.derby.iapi.services.monitor.ModuleControl.stop. Called by Monitor when this module is stopped, i.e. when the database is shut down.
public void	stopReplicationSlave() Overrides org.apache.derby.impl.db.BasicDatabase.stopReplicationSlave. Implements org.apache.derby.iapi.db.Database.stopReplicationSlave. Stop replication slave mode if replication slave mode is active and the network connection with the master is down
public void	verifyShutdownSlave() Verify that a connection to stop the slave has been made from here.
private void	verifySuccessfulBoot() Verify that the slave functionality has been properly started.

bootException	back to summary
private volatile StandardException bootException Set by the database boot thread if it fails before slave mode has been started properly (i.e., if inBoot is true). This exception will then be reported to the client connection.

dbname	back to summary
private String dbname

inBoot	back to summary
private volatile boolean inBoot True until this database has been successfully booted. Any exception that occurs while inBoot is true will be handed to the client thread booting this database.

inReplicationSlaveMode	back to summary
private volatile boolean inReplicationSlaveMode True until SlaveDatabaseBootThread has successfully booted the database. Does not happen until the failover command has been executed for this database

shutdownInitiated	back to summary
private volatile boolean shutdownInitiated

slaveFac	back to summary
private volatile SlaveFactory slaveFac

SlaveDatabase	back to summary
public SlaveDatabase()

Method Detail

boot	back to summary
public void boot(boolean create, Properties startParams) throws StandardException Overrides org.apache.derby.impl.db.BasicDatabase.boot. Implements org.apache.derby.iapi.services.monitor.ModuleControl.boot. Doc from org.apache.derby.iapi.services.monitor.ModuleControl.boot. Boot this module with the given properties. Creates a module instance that can be found using the findModule() methods of Monitor. The module can only be found using one of these findModule() methods once this method has returned. An implementation's boot method can throw StandardException. If it is thrown the module is not registered by the monitor and therefore cannot be found through a findModule(). In this case the module's stop() method is not called, thus throwing this exception must free up any resources. When create is true the contents of the properties object will be written to the service.properties of the persistent service. Thus any code that requires an entry in service.properties must explicitly place the value in this properties set using the put method. Typically the properties object contains one or more default properties sets, which are not written out to service.properties. These default sets are how callers modify the create process. In a JDBC connection database create the first set of defaults is a properties object that contains the attributes that were set on the jdbc:derby: URL. This attributes properties set has the second default properties set as its default. This set (which could be null) contains the properties that the user set on their DriverManager.getConnection() call, and are thus not owned by Derby code, and thus must not be modified by Derby code. When create is false the properties object contains all the properties set in the service.properties file plus a limited number of attributes from the JDBC URL attributes or connection properties set. This avoids properties set by the user compromising the boot process. An example of a property passed in from the JDBC world is the bootPassword for encrypted databases. Code should not hold onto the passed in properties reference after boot time as its contents may change underneath it. At least after the complete boot is completed, the links to all the default sets will be removed. Parameters create:boolean True if the database should be created startParams:Properties Configuration properties Exceptions StandardException: Module cannot be started.

boot

back to summary

public void boot(boolean create, Properties startParams) throws StandardException

Overrides org.apache.derby.impl.db.BasicDatabase.boot.

Implements org.apache.derby.iapi.services.monitor.ModuleControl.boot.

Doc from org.apache.derby.iapi.services.monitor.ModuleControl.boot.

Boot this module with the given properties. Creates a module instance that can be found using the findModule() methods of Monitor. The module can only be found using one of these findModule() methods once this method has returned.

An implementation's boot method can throw StandardException. If it is thrown the module is not registered by the monitor and therefore cannot be found through a findModule(). In this case the module's stop() method is not called, thus throwing this exception must free up any resources.

When create is true the contents of the properties object will be written to the service.properties of the persistent service. Thus any code that requires an entry in service.properties must explicitly place the value in this properties set using the put method.
Typically the properties object contains one or more default properties sets, which are not written out to service.properties. These default sets are how callers modify the create process. In a JDBC connection database create the first set of defaults is a properties object that contains the attributes that were set on the jdbc:derby: URL. This attributes properties set has the second default properties set as its default. This set (which could be null) contains the properties that the user set on their DriverManager.getConnection() call, and are thus not owned by Derby code, and thus must not be modified by Derby code.

When create is false the properties object contains all the properties set in the service.properties file plus a limited number of attributes from the JDBC URL attributes or connection properties set. This avoids properties set by the user compromising the boot process. An example of a property passed in from the JDBC world is the bootPassword for encrypted databases.

Code should not hold onto the passed in properties reference after boot time as its contents may change underneath it. At least after the complete boot is completed, the links to all the default sets will be removed.

Parameters

create:boolean: True if the database should be created
startParams:Properties: Configuration properties

Exceptions

StandardException:: Module cannot be started.

bootBasicDatabase	back to summary
private void bootBasicDatabase(boolean create, Properties params) throws StandardException

canSupport	back to summary
public boolean canSupport(Properties startParams) Overrides org.apache.derby.impl.db.BasicDatabase.canSupport. Implements org.apache.derby.iapi.services.monitor.ModuleSupportable.canSupport. Determines whether this Database implementation should be used to boot the database. Parameters startParams:Properties The properties used to decide if SlaveDatabase is the correct implementation of Database for the database to be booted. Returns:boolean true if the database is updatable (not read-only) and replication slave mode is specified in startParams

canSupport

back to summary

public boolean canSupport(Properties startParams)

Overrides org.apache.derby.impl.db.BasicDatabase.canSupport.

Implements org.apache.derby.iapi.services.monitor.ModuleSupportable.canSupport.

Determines whether this Database implementation should be used to boot the database.

Parameters

startParams:Properties: The properties used to decide if SlaveDatabase is the correct implementation of Database for the database to be booted.

Returns:boolean

true if the database is updatable (not read-only) and replication slave mode is specified in startParams

failover	back to summary
public void failover(String dbname) throws StandardException Overrides org.apache.derby.impl.db.BasicDatabase.failover. Implements org.apache.derby.iapi.db.Database.failover. Doc from org.apache.derby.iapi.db.Database.failover. Start failover for the given database. Parameters dbname:String the replication database that is being failed over. Exceptions StandardException: 1) If the failover succeeds, an exception is thrown to indicate that the master database was shutdown after a successful failover 2) If a failure occurs during network communication with slave.

failover

back to summary

public void failover(String dbname) throws StandardException

Overrides org.apache.derby.impl.db.BasicDatabase.failover.

Implements org.apache.derby.iapi.db.Database.failover.

Doc from org.apache.derby.iapi.db.Database.failover.

Start failover for the given database.

Parameters

dbname:String: the replication database that is being failed over.

Exceptions

StandardException:: 1) If the failover succeeds, an exception is thrown to indicate that the master database was shutdown after a successful failover 2) If a failure occurs during network communication with slave.

findServiceModule	back to summary
private static Object findServiceModule(final Object serviceModule, final String factoryInterface) throws StandardException Hides org.apache.derby.impl.db.BasicDatabase.findServiceModule. Must be private so that user code can't call this entry point.

findServiceModule

back to summary

private static Object findServiceModule(final Object serviceModule, final String factoryInterface) throws StandardException

Hides org.apache.derby.impl.db.BasicDatabase.findServiceModule.

Must be private so that user code can't call this entry point.

getAuthenticationService	back to summary
public AuthenticationService getAuthenticationService() throws StandardException Overrides org.apache.derby.impl.db.BasicDatabase.getAuthenticationService. Implements org.apache.derby.iapi.db.Database.getAuthenticationService. Doc from org.apache.derby.iapi.db.Database.getAuthenticationService. This method returns the authentication service handle for the database. Note There is always a Authentication Service per database and at the system level. Returns:AuthenticationService The authentication service handle for the database Exceptions StandardException: standard Derby exception policy

getAuthenticationService

back to summary

public AuthenticationService getAuthenticationService() throws StandardException

Overrides org.apache.derby.impl.db.BasicDatabase.getAuthenticationService.

Implements org.apache.derby.iapi.db.Database.getAuthenticationService.

Doc from org.apache.derby.iapi.db.Database.getAuthenticationService.

This method returns the authentication service handle for the database.

Note

There is always a Authentication Service per database and at the system level.

Returns:AuthenticationService

The authentication service handle for the database

Exceptions

StandardException:: standard Derby exception policy

getContextService	back to summary
private static ContextService getContextService() Hides org.apache.derby.impl.db.BasicDatabase.getContextService. Must be private so that user code can't call this entry point.

getContextService

back to summary

private static ContextService getContextService()

Hides org.apache.derby.impl.db.BasicDatabase.getContextService.

Must be private so that user code can't call this entry point.

handleShutdown	back to summary
private void handleShutdown(StandardException shutdownCause) Used to shutdown this database. If an error occurs as part of the database boot process, we hand the exception that caused boot to fail to the client thread. The client thread will in turn shut down this database. If an error occurs at a later stage than during boot, we shut down the database by setting up a connection with the shutdown attribute. The internal connection is required because database shutdown requires EmbedConnection to do cleanup. Parameters shutdownCause:StandardException the reason why the database needs to be shutdown

handleShutdown

back to summary

private void handleShutdown(StandardException shutdownCause)

Used to shutdown this database. If an error occurs as part of the database boot process, we hand the exception that caused boot to fail to the client thread. The client thread will in turn shut down this database. If an error occurs at a later stage than during boot, we shut down the database by setting up a connection with the shutdown attribute. The internal connection is required because database shutdown requires EmbedConnection to do cleanup.

Parameters

shutdownCause:StandardException: the reason why the database needs to be shutdown

isInSlaveMode	back to summary
public boolean isInSlaveMode() Overrides org.apache.derby.impl.db.BasicDatabase.isInSlaveMode. Implements org.apache.derby.iapi.db.Database.isInSlaveMode. Doc from org.apache.derby.iapi.db.Database.isInSlaveMode. Used to indicated whether the database is in the replication slave mode. Returns:boolean true if this database is in replication slave mode, false otherwise.

isInSlaveMode

back to summary

public boolean isInSlaveMode()

Overrides org.apache.derby.impl.db.BasicDatabase.isInSlaveMode.

Implements org.apache.derby.iapi.db.Database.isInSlaveMode.

Doc from org.apache.derby.iapi.db.Database.isInSlaveMode.

Used to indicated whether the database is in the replication slave mode.

Returns:boolean: true if this database is in replication slave mode, false otherwise.

isSlaveFactorySet	back to summary
private boolean isSlaveFactorySet() If slaveFac (the reference to the SlaveFactory) has not already been set, this method will try to set it by calling Monitor.findServiceModule. If slavFac was already set, the method does not do anything. Returns:boolean true if slaveFac is set after calling this method, false otherwise

isSlaveFactorySet

back to summary

private boolean isSlaveFactorySet()

If slaveFac (the reference to the SlaveFactory) has not already been set, this method will try to set it by calling Monitor.findServiceModule. If slavFac was already set, the method does not do anything.

Returns:boolean: true if slaveFac is set after calling this method, false otherwise

setupConnection	back to summary
public LanguageConnectionContext setupConnection(ContextManager cm, String user, String drdaID, String dbname) throws StandardException Overrides org.apache.derby.impl.db.BasicDatabase.setupConnection. Implements org.apache.derby.iapi.db.Database.setupConnection. Doc from org.apache.derby.iapi.db.Database.setupConnection. Sets up a connection to the Database, owned by the given user. The JDBC version of getConnection takes a URL. The purpose of the URL is to tell the driver where the database system is. By the time we get here, we have found the database system (that's how we're making this method call), so the URL is not necessary to establish the connection here. The driver should remember the URL that was used to establish the connection, so it can implement the DatabaseMetaData.getURL() method. Parameters cm:ContextManager The context manager user:String The UserID of the user getting the connection drdaID:String The drda id of the connection (from network server) dbname:String The database name Returns:LanguageConnectionContext A new LanguageConnectionContext Exceptions StandardException: thrown if unable to create the connection.

setupConnection

back to summary

public LanguageConnectionContext setupConnection(ContextManager cm, String user, String drdaID, String dbname) throws StandardException

Overrides org.apache.derby.impl.db.BasicDatabase.setupConnection.

Implements org.apache.derby.iapi.db.Database.setupConnection.

Doc from org.apache.derby.iapi.db.Database.setupConnection.

Sets up a connection to the Database, owned by the given user. The JDBC version of getConnection takes a URL. The purpose of the URL is to tell the driver where the database system is. By the time we get here, we have found the database system (that's how we're making this method call), so the URL is not necessary to establish the connection here. The driver should remember the URL that was used to establish the connection, so it can implement the DatabaseMetaData.getURL() method.

Parameters

cm:ContextManager: The context manager
user:String: The UserID of the user getting the connection
drdaID:String: The drda id of the connection (from network server)
dbname:String: The database name

Returns:LanguageConnectionContext

A new LanguageConnectionContext

Exceptions

StandardException:: thrown if unable to create the connection.

stop	back to summary
public void stop() Overrides org.apache.derby.impl.db.BasicDatabase.stop. Implements org.apache.derby.iapi.services.monitor.ModuleControl.stop. Called by Monitor when this module is stopped, i.e. when the database is shut down. When the database is shut down using the stopSlave command, the stopReplicationSlave method has already been called when this method is called. In this case, the replication functionality has already been stopped. If the database is shutdown as part of a system shutdown, however, we need to cleanup slave replication as part of database shutdown.

stop

back to summary

public void stop()

Overrides org.apache.derby.impl.db.BasicDatabase.stop.

Implements org.apache.derby.iapi.services.monitor.ModuleControl.stop.

Called by Monitor when this module is stopped, i.e. when the database is shut down. When the database is shut down using the stopSlave command, the stopReplicationSlave method has already been called when this method is called. In this case, the replication functionality has already been stopped. If the database is shutdown as part of a system shutdown, however, we need to cleanup slave replication as part of database shutdown.

stopReplicationSlave	back to summary
public void stopReplicationSlave() throws SQLException Overrides org.apache.derby.impl.db.BasicDatabase.stopReplicationSlave. Implements org.apache.derby.iapi.db.Database.stopReplicationSlave. Stop replication slave mode if replication slave mode is active and the network connection with the master is down Exceptions SQLException: Thrown on error, if not in replication slave mode or if the network connection with the master is not down

stopReplicationSlave

back to summary

public void stopReplicationSlave() throws SQLException

Overrides org.apache.derby.impl.db.BasicDatabase.stopReplicationSlave.

Implements org.apache.derby.iapi.db.Database.stopReplicationSlave.

Stop replication slave mode if replication slave mode is active and the network connection with the master is down

Exceptions

SQLException:: Thrown on error, if not in replication slave mode or if the network connection with the master is not down

verifyShutdownSlave	back to summary
public void verifyShutdownSlave() throws StandardException Verify that a connection to stop the slave has been made from here. If verified, the database context is given to the method caller. This will ensure this database is shutdown when an exception with database severity is thrown. If not verified, an exception is thrown. Exceptions StandardException: Thrown if a stop slave connection attempt was not made from this class

verifyShutdownSlave

back to summary

public void verifyShutdownSlave() throws StandardException

Verify that a connection to stop the slave has been made from here. If verified, the database context is given to the method caller. This will ensure this database is shutdown when an exception with database severity is thrown. If not verified, an exception is thrown.

Exceptions

StandardException:: Thrown if a stop slave connection attempt was not made from this class

verifySuccessfulBoot	back to summary
private void verifySuccessfulBoot() throws StandardException Verify that the slave functionality has been properly started. This method will block until a successful slave startup has been confirmed, or it will throw the exception that caused it to fail.

public Class SlaveDatabase

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class SlaveDatabase.SlaveDatabaseBootThread

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail