org.rhq.enterprise.server.installer

Interface InstallerService

All Known Implementing Classes:

InstallerServiceImpl

public interface InstallerService

Author:

John Mazzitelli

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	InstallerService.AlreadyInstalledException
static class	InstallerService.AutoInstallDisabledException

Method Summary

Methods

Modifier and Type	Method and Description
ArrayList<ServerDetails>	getAllServerDetails(String connectionUrl, String username, String password) Returns details on all servers that are registered in the database.
String	getAppServerVersion() Returns the version string for the app server itself (e.g.
String	getInstallationResults() Use this to determine if the server has already been completely installed or not.
String	getOperatingSystem() Returns the general type of operating system the server is running on (e.g.
ServerDetails	getServerDetails(String connectionUrl, String username, String password, String serverName) Returns details on a specific server that is registered in the database.
ArrayList<String>	getServerNames(String connectionUrl, String username, String password) Returns a list of all registered servers in the database.
HashMap<String,String>	getServerProperties() Returns the rhq-server.properties values in a map.
void	install(HashMap<String,String> serverProperties, ServerDetails serverDetails, String existingSchemaOption) Starts the installation process.
boolean	isDatabaseSchemaExist(String connectionUrl, String username, String password) Tests to see if there is already a schema installed.
void	listServers() This simply logs a list of all known registered servers found in the database.
String	obfuscatePassword(String clearTextPassword) Given a database password, this will obfuscate it.
HashMap<String,String>	preInstall() Call this prior to installing to see if we are ready to install.
void	prepareDatabase(HashMap<String,String> serverProperties, ServerDetails serverDetails, String existingSchemaOption) Prepares the database.
void	test() This simply verifies the server configuration but doesn't perform the actual install.
String	testConnection(String connectionUrl, String username, String password) Tests that the database can be connected to with the given URL and credentials.

Method Detail

obfuscatePassword

String obfuscatePassword(String clearTextPassword)
                         throws Exception

Given a database password, this will obfuscate it. The obfuscated password should be used within rhq-server.properties.

Parameters:

clearTextPassword - the password to obfuscate

Returns:

the obfuscated password

Throws:

Exception

listServers

void listServers()
                 throws Exception

This simply logs a list of all known registered servers found in the database.

Throws:

Exception

test

void test()
          throws InstallerService.AutoInstallDisabledException,
                 InstallerService.AlreadyInstalledException,
                 Exception

This simply verifies the server configuration but doesn't perform the actual install. You can use this to see if, for example, the database settings are correct or the installer can successfully connect to the running AS instance where RHQ is to be installed.

Throws:

InstallerService.AutoInstallDisabledException - if the server configuration properties does not have auto-install enabled

InstallerService.AlreadyInstalledException - if it appears the installer was already run and the server is fully installed

Exception - some other exception that should disallow the installation from continuing

preInstall

HashMap<String,String> preInstall()
                                  throws InstallerService.AutoInstallDisabledException,
                                         InstallerService.AlreadyInstalledException,
                                         Exception

Call this prior to installing to see if we are ready to install. This will do some pre-install checks - if the installation should proceed, the map of server properties is returned. Exceptions are thrown if the install should not proceed.

Returns:

properties if the caller should next call install(HashMap, ServerDetails, String).

Throws:

InstallerService.AutoInstallDisabledException - if the server configuration properties does not have auto-install enabled

InstallerService.AlreadyInstalledException - if it appears the installer was already run and the server is fully installed

Exception - some other exception that should disallow the installation from continuing

getInstallationResults

String getInstallationResults()
                              throws Exception

Use this to determine if the server has already been completely installed or not. This returns a String to indicate the last installation attempt. If this returns null, then the installer has not done anything yet - you need to complete the installation. If an empty string is returned, it means the installer ran and it appears the application has successfully installed. If a non-empty string is returned, it means the installer attempted to complete the installation, but an error occurred. When a non-empty string is returned, it means that an administrator probably has to do some manual intervention because something went wrong with the application deployment.

Returns:

indicating of the last installation attempt (see above)

Throws:

Exception - if it cannot be determined if the server has been fully installed.

install

void install(HashMap<String,String> serverProperties,
           ServerDetails serverDetails,
           String existingSchemaOption)
             throws InstallerService.AutoInstallDisabledException,
                    InstallerService.AlreadyInstalledException,
                    Exception

Starts the installation process. Once complete, the installer has nothing more it needs to do.

Parameters:

serverProperties - the server's settings to use. These will be persisted to the server's .properties file.

serverDetails - details on the server being installed. If in auto-install mode, this value is ignored and can be anything.

existingSchemaOption - if not in auto-install mode, this tells the installer what to do with any existing schema. Must be one of the names of the ServerInstallUtil.ExistingSchemaOption enum. If in auto-install mode, this value is ignored and can be anything.

Throws:

InstallerService.AutoInstallDisabledException - if the server configuration properties does not have auto-install enabled

InstallerService.AlreadyInstalledException - if it appears the installer was already run and the server is fully installed

Exception - some other exception that should disallow the installation from continuing

prepareDatabase

void prepareDatabase(HashMap<String,String> serverProperties,
                   ServerDetails serverDetails,
                   String existingSchemaOption)
                     throws Exception

Prepares the database. This is either going to do a full clean db setup or a db upgrade depending on the existingSchemaOption parameter unless autoinstall setting is on, in which case the autoinstall schema setting in serverProperties parameter will tell this method what to do. NOTE: if not in auto-install mode, the database password is assumed to be in clear text (i.e. unencoded). If in auto-install mode, the database password must be encoded already.

Parameters:

serverProperties - the server's settings to use. These will be persisted to the server's .properties file.

serverDetails - details on the server being installed. If in auto-install mode, this value is ignored and can be anything.

existingSchemaOption - if not in auto-install mode, this tells the installer what to do with any existing schema. Must be one of the names of the ServerInstallUtil.ExistingSchemaOption enum. If in auto-install mode, this value is ignored and can be anything.

Throws:

Exception - failed to successfully prepare the database

getServerNames

ArrayList<String> getServerNames(String connectionUrl,
                               String username,
                               String password)
                                 throws Exception

Returns a list of all registered servers in the database.

Parameters:

connectionUrl -

username -

password -

Returns:

list of all existing servers registered in the database.

Throws:

Exception

getAllServerDetails

ArrayList<ServerDetails> getAllServerDetails(String connectionUrl,
                                           String username,
                                           String password)
                                             throws Exception

Returns details on all servers that are registered in the database.

Parameters:

connectionUrl -

username -

password -

Returns:

the details of all known servers

Throws:

Exception

getServerDetails

ServerDetails getServerDetails(String connectionUrl,
                             String username,
                             String password,
                             String serverName)
                               throws Exception

Returns details on a specific server that is registered in the database.

Parameters:

connectionUrl -

username -

password -

serverName - the name of the server whose details are to be retrieved

Returns:

the details of the server or null if the server does not exist

Throws:

Exception

isDatabaseSchemaExist

boolean isDatabaseSchemaExist(String connectionUrl,
                            String username,
                            String password)
                              throws Exception

Tests to see if there is already a schema installed.

Parameters:

connectionUrl -

username -

password -

Returns:

true if there appears to be a schema installed in the database already.

Throws:

Exception

testConnection

String testConnection(String connectionUrl,
                    String username,
                    String password)
                      throws Exception

Tests that the database can be connected to with the given URL and credentials.

Parameters:

connectionUrl -

username -

password -

Returns:

null if the connection succeeded; this will be an error message if failed

Throws:

Exception

getServerProperties

HashMap<String,String> getServerProperties()
                                           throws Exception

Returns the rhq-server.properties values in a map.

Returns:

server properties

Throws:

Exception

getAppServerVersion

String getAppServerVersion()
                           throws Exception

Returns the version string for the app server itself (e.g. "7.1.2.Final").

Returns:

version string of app server

Throws:

Exception

getOperatingSystem

String getOperatingSystem()
                          throws Exception

Returns the general type of operating system the server is running on (e.g. "Linux").

Returns:

os type name

Throws:

Exception