com.sonicsw.mf.mgmtapi.runtime
Interface IHostManagerProxy

public interface IHostManagerProxy

Provides remote access to the Host Manager. Used, in particular, for Centralized Install related management. The following is an example of connecting to 'AutoTestContainer' (a root container); Setting up the new container '/Containers/AutoTestContainer'; and launching it:

 Hashtable env = new Hashtable();
 env.put(IContainerConstants.CONNECTIONURLS_ATTR, "tcp://localhost:2506");
 JMSConnectorAddress address = new JMSConnectorAddress(env);
 JMSConnectorClient connector = new JMSConnectorClient();
 connector.connect(address);
 System.out.println("Connected...");

 //Create a proxy to the Host Manager in the AutoTestContainer container
 IHostManagerProxy hostManager = MFProxyFactory.createHostManagerProxy(connector, new ObjectName("Domain1.AutoTestContainer:ID=HOST MANAGER"));

 //Setup the SonicRemote container
 Properties containerProps = new Properties();
 containerProps.put("WINDOWS_SERVICE_NAME", "AutoTestContainer");
 containerProps.put("DOMAIN_NAME", "Domain1");
 containerProps.put("CREATE_IF_DOES_NOT_EXIST", "true");
 containerProps.put("CONTAINER_PATH", "/Containers/AutoTestContainer");
 containerProps.put("ConnectionURLs", "tcp://localhost:2506");
 containerProps.put("DefaultPassword", "Administrator");
 containerProps.put("DefaultUser", "Administrator");
 System.out.println("Setup result: " + hostManager.setupContainer(containerProps, null));

 //Launch the SonicRemote container from a script
 System.out.println("Launch result: " + hostManager.launchContainer("AutoTestContainer", false));
 

Method Summary

IRemoteCallResult	deleteFiles(java.lang.String pathOfdirectoryOrFile, boolean deleteContent) Delete the file or directory.
IRemoteCallResult	downloadFileFromDS(java.lang.String dsFilePath, java.lang.String destinationFilePath, boolean rewriteIfExists, boolean expandZip) Download a file from the Directory Service into the container's file-system.
java.lang.String[]	getAllHostnamesAndIPs(boolean includeLoopback) Gets all known hostnames and ip addresses of this machine.
IRemoteCallResult	getFiles(java.lang.String srcFilePath, java.lang.String destinationFilePath, boolean rewriteIfExists) Copy a file from the container's file-system to the client's file system.
java.util.Properties	getJVMProperties() Returns the system properties of the container.
IRemoteCallResult	installLauncher(java.lang.String targetSonicHome) Install the launcher that launched the container that hosts this HM under targetSonicHome
IRemoteCallResult	launchContainer(java.lang.String containerName, boolean launchAsWindowsService) Launches a container that was previously setup.
IRemoteCallResult	launchContainer(java.lang.String sonicHome, java.lang.String containerName, boolean launchAsWindowsService) Launches a container that was previously setup in a different home.
IFileDescriptor[]	listDirectory(java.lang.String directoryPath) Return the list of files and directories under directoryPath
IRemoteCallResult	putFiles(java.lang.String sourceFilePath, java.lang.String destinationFilePath, boolean rewriteIfExists) Copy a file or a directory from the client's file system to the container's file-system.
void	reload() Invokes the reload operation.
IRemoteExecResult	remoteExec(java.lang.String[] cmdarray, java.lang.String[] envp, java.lang.String workDirPath, byte[] inputBytes) The remoteExec call executes java.lang.Runtime.exec on the target container.
IRemoteCallResult	removeContainer(java.lang.String containerName) Uninstall the Windows Service (if installed) and remove the files from the working directory.
IRemoteCallResult	setupContainer(java.util.Properties properties, java.lang.String INIEncryptionPassword) Setup a new container by generating the launch and Windows Service scripts and the container.ini file.
IRemoteCallResult	setupContainer(java.lang.String containerDSPath, java.util.Properties unConfiguredProps, java.lang.String INIEncryptionPassword) Setup a new container by generating the launch and Windows Service scripts and the container.ini file.
IRemoteCallResult	setupContainer(java.lang.String sonicHome, java.lang.String launcherVersion, java.util.Properties properties, java.lang.String INIEncryptionPassword) Setup a new container under the specified soniv home.
void	start() Invokes the start operation.
void	stop() Invokes the stop operation.

Method Detail

deleteFiles

IRemoteCallResult deleteFiles(java.lang.String pathOfdirectoryOrFile,
                              boolean deleteContent)

Delete the file or directory. If 'deleteContent' is false and the directory is not empty the operation will fail; if true, the content of the directory will be first deleted

Parameters:

pathOfdirectoryOrFile - the path of a directory or a file

deleteContent - if true and 'pathOfdirectoryOrFile' is a directory, deletes the directory's content

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

downloadFileFromDS

IRemoteCallResult downloadFileFromDS(java.lang.String dsFilePath,
                                     java.lang.String destinationFilePath,
                                     boolean rewriteIfExists,
                                     boolean expandZip)

Download a file from the Directory Service into the container's file-system.

Parameters:

dsFilePath - File path in the DS

destinationFilePath - destination path on the container side

rewriteIfExists - fails if false and the file already exists

expandZip - if 'true' expand the zip file after downloading it

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

getAllHostnamesAndIPs

java.lang.String[] getAllHostnamesAndIPs(boolean includeLoopback)

Gets all known hostnames and ip addresses of this machine. This will (on request) include the loopback interface (localhost) as well as all ip address/hostnames of all network interfaces.

Hostnames are added as strings to the set as lower case values.

Warning: this method can be slow, since for each known address of each network interface we do reverse dns lookup twice.

Parameters:

includeLoopback - if the loopback address and hostnames should be included or not

Returns:

array of all known ip addresses and hostnames both domain name qualified and unqualified.

Throws:

ProxyRuntimeException

getFiles

IRemoteCallResult getFiles(java.lang.String srcFilePath,
                           java.lang.String destinationFilePath,
                           boolean rewriteIfExists)

Copy a file from the container's file-system to the client's file system. This is intended for small to medium size files since the file is fully read into memory.

Parameters:

srcFilePath - The file path on the container side

destinationFilePath - The file path on the client side

rewriteIfExists - fails if false and the file already exists

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

getJVMProperties

java.util.Properties getJVMProperties()

Returns the system properties of the container.

Returns:

Returns the system properties of the container

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

installLauncher

IRemoteCallResult installLauncher(java.lang.String targetSonicHome)

Install the launcher that launched the container that hosts this HM under targetSonicHome

Parameters:

targetSonicHome - install the launcher under this directory

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

launchContainer

IRemoteCallResult launchContainer(java.lang.String containerName,
                                  boolean launchAsWindowsService)

Launches a container that was previously setup. If launchAsWindowsService is true and the container is launched on Windows then the method would launch the container as Windows Service. The method starts an asynchronous process to start the container and doesn't wait for it to actually start up.

Parameters:

containerName - Container name

launchAsWindowsService - if true and on Windows will launch the container as Windows Service

Returns:

success/failure result; the successful start of the container startup process doesn't guarantee an unltimate successful startup.

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

launchContainer

IRemoteCallResult launchContainer(java.lang.String sonicHome,
                                  java.lang.String containerName,
                                  boolean launchAsWindowsService)

Launches a container that was previously setup in a different home. If launchAsWindowsService is true and the container is launched on Windows then the method would launch the container as Windows Service. The method starts an asynchronous process to start the container and doesn't wait for it to actually start up.

Parameters:

sonicHome - the home of this container

containerName - Container name

launchAsWindowsService - if true and on Windows will launch the container as Windows Service

Returns:

success/failure result; the successful start of the container startup process doesn't guarantee an unltimate successful startup.

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

listDirectory

IFileDescriptor[] listDirectory(java.lang.String directoryPath)

Return the list of files and directories under directoryPath

Parameters:

directoryPath - an absolute path or a path relative to the working directory of the container

Returns:

list of sub-directories and files

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

putFiles

IRemoteCallResult putFiles(java.lang.String sourceFilePath,
                           java.lang.String destinationFilePath,
                           boolean rewriteIfExists)

Copy a file or a directory from the client's file system to the container's file-system. This is intended for small to medium size files since the file is fully read into memory.

Parameters:

sourceFilePath - Client side path

destinationFilePath - destination path on the container side

rewriteIfExists - fails if false and the file already exists

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

reload

void reload()

Invokes the reload operation.

Asynchronously reload the component and restart the component if it was previously online.

Impact: ACTION

remoteExec

IRemoteExecResult remoteExec(java.lang.String[] cmdarray,
                             java.lang.String[] envp,
                             java.lang.String workDirPath,
                             byte[] inputBytes)

The remoteExec call executes java.lang.Runtime.exec on the target container. The standard output and standard error of the call are returned in IRemoteExecResult as byte arrays - that imposes some practical limit on the size of the output.

Parameters:

cmdarray - a specified system command.

envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process.

workDirPath - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process.

inputBytes - Standrd input for the process (or null if there is no input)

Returns:

success/failure result and the standard output and error generated by the remote execution

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

removeContainer

IRemoteCallResult removeContainer(java.lang.String containerName)

Uninstall the Windows Service (if installed) and remove the files from the working directory. The container must be must shutdown prior to calling removeContainer.

Parameters:

containerName - Container name

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result

setupContainer

IRemoteCallResult setupContainer(java.util.Properties properties,
                                 java.lang.String INIEncryptionPassword)

Setup a new container by generating the launch and Windows Service scripts and the container.ini file. The generated container scripts will use the same launcher version used to launch the remote container.

Parameters:

properties - the container setup properties

INIEncryptionPassword - an optional password for INI file encryption

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result Example Properties containerProps = new Properties(); containerProps.put("WINDOWS_SERVICE_NAME", "SonicRemote"); containerProps.put("DOMAIN_NAME", "Domain1"); containerProps.put("CREATE_IF_DOES_NOT_EXIST", "true"); containerProps.put("CONTAINER_PATH", "/Containers/SonicRemote"); containerProps.put("ConnectionURLs", "tcp://localhost:2506"); containerProps.put("DefaultPassword", "Administrator"); containerProps.put("DefaultUser", "Administrator");

setupContainer

IRemoteCallResult setupContainer(java.lang.String containerDSPath,
                                 java.util.Properties unConfiguredProps,
                                 java.lang.String INIEncryptionPassword)

Setup a new container by generating the launch and Windows Service scripts and the container.ini file. The generated container scripts will use the same launcher version used to launch the remote container. Only non DS configured properties (see example below) should be passed in the 'unConfiguredProps' parameter. The configured properties are retrieved from the container configuration in the DS.

Parameters:

containerDSPath - the path of the container configuration in the DS

unConfiguredProps - the container unconfigured setup properties

INIEncryptionPassword - an optional password for INI file encryption

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result Properties Example Properties unConfiguredProps = new Properties(); unConfiguredProps.put("WINDOWS_SERVICE_NAME", "SonicRemote");

setupContainer

IRemoteCallResult setupContainer(java.lang.String sonicHome,
                                 java.lang.String launcherVersion,
                                 java.util.Properties properties,
                                 java.lang.String INIEncryptionPassword)

Setup a new container under the specified soniv home. NOTE: This method should be used only in special cases. The setupContainer methods that implictly use the same sonic home used by the current container should be typically used.

Parameters:

sonicHome - the sonic home used by the new container

launcherVersion - the launcher version used by the new container. If 'null' will use the same launcher version used to launch the remote container.

properties - the container setup properties

INIEncryptionPassword - an optional password for INI file encryption

Returns:

success/failure result

Throws:

ProxyRuntimeException - thrown due to communication failure that prevented the remote execution or the reception of the execution result Example Properties containerProps = new Properties(); containerProps.put("WINDOWS_SERVICE_NAME", "SonicRemote"); containerProps.put("DOMAIN_NAME", "Domain1"); containerProps.put("CREATE_IF_DOES_NOT_EXIST", "true"); containerProps.put("CONTAINER_PATH", "/Containers/SonicRemote"); containerProps.put("ConnectionURLs", "tcp://localhost:2506"); containerProps.put("DefaultPassword", "Administrator"); containerProps.put("DefaultUser", "Administrator");

start

void start()

Invokes the start operation.

Start providing service.

Impact: ACTION

See Also:

stop()

stop

void stop()

Invokes the stop operation.

Stop providing service.

Impact: ACTION

See Also:

start()