com.endeca.soleng.eac.toolkit.utility
Class Utility

java.lang.Object
  com.endeca.soleng.eac.toolkit.base.EacElement
      com.endeca.soleng.eac.toolkit.utility.Utility

Direct Known Subclasses:

BackupUtility, CopyUtility, FileUtility, RollbackUtility, ShellUtility

public class Utility
extends EacElement

The Utility class is the base class from which all utility implementations extend. This includes core utilities copy, backup, shell and rollback as well as custom extensions of those utilities that expose common utility invocations that may be used in deployments. This class provides methods for interacting with the EAC's utility web service, including starting, stopping and querying for the status of a utility invocation. Utility objects are designed for easy construction and initialization by other Java classes in the toolkit. To that end, constructors are provided that set the application name and EAC host and port (without which, no EAC interaction would be possible). Initializer methods are also provided, exposing single-method interfaces for other objects to set up common utilities for invocation. Utilities can also be defined in the app configuration document. To facilitate this, Utility objects are designed as simple, Spring-friendly Beans, providing empty constructors and getters and setters for all fields.

Author:

sshusteff

Field Summary

protected static int	EAC_MAX_TOKEN_LENGTH Maximum token length that the EAC can handle
protected static java.lang.String	ENDECA_CONF Holds the ENDECA_CONF environment variable
protected static boolean	IS_WINDOWS Are we running on a Windows system?
protected static int	WINDOWS_MAX_PATH_LENGTH Maximum absolute path allowed under the Windows filesystem

Fields inherited from class com.endeca.soleng.eac.toolkit.base.EacElement

appName, dataPrefix, eacHost, eacPort, elementId, lockManager, logDir, sslEnabled, workingDir

Constructor Summary

Utility()
Empty constructor, for convenience in using utilities as beans.

Utility(java.lang.String appName, java.lang.String eacHost, int eacPort, boolean sslEnabled)
Default constructor.

Method Summary

com.endeca.eac.client.RunUtilityType	buildEacStub() Builds a RunUtilityType object to send to the EAC.
java.util.Map<java.lang.String,java.lang.Boolean>	getDirContents(java.lang.String dir, java.lang.String host) Retrieves the list of files found in the specified directory on the specified host.
long	getMaxMissedStatusChecksAllowed()
long	getMaxWaitTimeSeconds()
long	getMinWaitTimeSeconds()
long	getNonNullPositiveLongValueOrDefault(long value, long defaultValue)
int	getNumMissedStatusChecks()
long	getSlowPollingIntervalMs()
long	getStandardPollingIntervalMs()
com.endeca.eac.client.StateType	getStatus() Retrieves the status of the utility.
void	incrementMissedStatusQueries()
protected void	initializeEacStub(com.endeca.eac.client.RunUtilityType stub)
boolean	isActive() Returns true if the utility is active (i.e.
boolean	isFailed() Returns true if the utility failed when it was run most recently.
protected int	maximumAllowedTokenLength()
void	run() Runs the utility synchronously.
static void	runInParallel(java.util.List<Utility> utilities) Static method to run a set of utilities in parallel.
void	setElementId(java.lang.String elementId)
void	setMaxMissedStatusQueriesAllowed(long maxMissedStatusQueriesAllowed)
void	setMaxWaitSeconds(long maxWaitSeconds)
void	setMinWaitSeconds(long minWaitSeconds)
void	setNumMissedStatusChecks(int numMissedStatusQueries)
void	setPollingIntervalMs(long pollingIntervalMs)
void	setSlowPollingIntervalMs(long slowPollingIntervalMs)
void	start() Starts the utility.
void	stop() Stops the utility.
boolean	waitForFinished() Waits for the utility to finish, by polling for its status every second, until the maximum wait time has elapsed.

Methods inherited from class com.endeca.soleng.eac.toolkit.base.EacElement

getAppName, getDataPrefix, getEacHost, getEacPort, getElementId, getLockManager, getLogDir, getWorkingDir, isSslEnabled, setAppName, setDataPrefix, setEacHost, setEacPort, setLockManager, setLogDir, setSslEnabled, setWorkingDir

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ENDECA_CONF

protected static final java.lang.String ENDECA_CONF

Holds the ENDECA_CONF environment variable

EAC_MAX_TOKEN_LENGTH

protected static final int EAC_MAX_TOKEN_LENGTH

Maximum token length that the EAC can handle

See Also:

Constant Field Values

WINDOWS_MAX_PATH_LENGTH

protected static final int WINDOWS_MAX_PATH_LENGTH

Maximum absolute path allowed under the Windows filesystem

See Also:

Constant Field Values

IS_WINDOWS

protected static final boolean IS_WINDOWS

Are we running on a Windows system?

Constructor Detail

Utility

public Utility(java.lang.String appName,
               java.lang.String eacHost,
               int eacPort,
               boolean sslEnabled)
        throws AppConfigurationException

Default constructor.

Throws:

AppConfigurationException - If the application name or EAC host is null.

Utility

public Utility()

Empty constructor, for convenience in using utilities as beans.

Method Detail

runInParallel

public static void runInParallel(java.util.List<Utility> utilities)
                          throws EacCommunicationException,
                                 EacComponentControlException

Static method to run a set of utilities in parallel. Starts each utility, then waits for each to complete and throws an exception if any of them fail. Because utilities are being started in parallel, and the EAC doesn't allow multiple utilities to be started with the same token/ID, this method will append a timestamp to any ID if a previous utility had the same ID.

Parameters:

utilities - List of utilities to execute.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of a utility from the EAC.

EacComponentControlException - If an error occurs while trying to start a utility.

run

public void run()
         throws EacCommunicationException,
                EacComponentControlException

Runs the utility synchronously. Starts the utility, polls for the status until the utility fails or stops.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to start the utility.

start

public void start()
           throws EacCommunicationException,
                  EacComponentControlException

Starts the utility.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to start the utility.

getDirContents

public java.util.Map<java.lang.String,java.lang.Boolean> getDirContents(java.lang.String dir,
                                                                        java.lang.String host)
                                                                 throws EacCommunicationException

Retrieves the list of files found in the specified directory on the specified host. Files are returned in a map, where the key is the file name and the value is a boolean indicating whether it is a directory.

Parameters:

dir - The absolute directory whose files are to be listed.

host - The target host on which the directory is found.

Returns:

Returns a map of files found in the specified directory or an empty list, keying on file name with boolean values indicating whether entries are directories

Throws:

EacCommunicationException

stop

public void stop()
          throws EacCommunicationException,
                 EacComponentControlException

Stops the utility.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to stop the utility.

getStatus

public com.endeca.eac.client.StateType getStatus()
                                          throws EacCommunicationException,
                                                 EacComponentControlException

Retrieves the status of the utility.

Returns:

Returns a representation of the utility's status.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to check the status of the utility.

waitForFinished

public boolean waitForFinished()
                        throws EacCommunicationException,
                               EacComponentControlException

Waits for the utility to finish, by polling for its status every second, until the maximum wait time has elapsed. If the utility hasn't stopped after the maximum wait time elapses, this method returns false. If a minimum wait time has been specified, this method will poll once per minute until the minimum wait time has been reached and then will begin polling once per second until the utility finishes or the maximum wait time has elapsed.

Returns:

Returns true if the utility finished within the allotted wait time.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to check the status of the utility.

isActive

public boolean isActive()
                 throws EacCommunicationException,
                        EacComponentControlException

Returns true if the utility is active (i.e. not failed or stopped).

Returns:

Returns true of the utility is active.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to check the status of the utility.

isFailed

public boolean isFailed()
                 throws EacCommunicationException,
                        EacComponentControlException

Returns true if the utility failed when it was run most recently.

Returns:

Returns true of the utility failed.

Throws:

EacCommunicationException - If a communication error occurs while requesting the status of the utility from the EAC.

EacComponentControlException - If an error occurs while trying to check the status of the utility.

buildEacStub

public com.endeca.eac.client.RunUtilityType buildEacStub()

Builds a RunUtilityType object to send to the EAC. If necessary, translates or transforms fields to match the EAC's requirements.

Returns:

Returns the RunUtilityType WSDL stub object for this Utility.

initializeEacStub

protected void initializeEacStub(com.endeca.eac.client.RunUtilityType stub)

maximumAllowedTokenLength

protected int maximumAllowedTokenLength()

setElementId

public void setElementId(java.lang.String elementId)

Overrides:

setElementId in class EacElement

getNonNullPositiveLongValueOrDefault

public long getNonNullPositiveLongValueOrDefault(long value,
                                                 long defaultValue)

getMaxMissedStatusChecksAllowed

public long getMaxMissedStatusChecksAllowed()

getStandardPollingIntervalMs

public long getStandardPollingIntervalMs()

getSlowPollingIntervalMs

public long getSlowPollingIntervalMs()

getMinWaitTimeSeconds

public long getMinWaitTimeSeconds()

getMaxWaitTimeSeconds

public long getMaxWaitTimeSeconds()

getNumMissedStatusChecks

public int getNumMissedStatusChecks()

setNumMissedStatusChecks

public void setNumMissedStatusChecks(int numMissedStatusQueries)

incrementMissedStatusQueries

public void incrementMissedStatusQueries()

setMinWaitSeconds

public void setMinWaitSeconds(long minWaitSeconds)

setMaxWaitSeconds

public void setMaxWaitSeconds(long maxWaitSeconds)

setMaxMissedStatusQueriesAllowed

public void setMaxMissedStatusQueriesAllowed(long maxMissedStatusQueriesAllowed)

setPollingIntervalMs

public void setPollingIntervalMs(long pollingIntervalMs)

setSlowPollingIntervalMs

public void setSlowPollingIntervalMs(long slowPollingIntervalMs)