com.tangosol.coherence.dslquery.internal

Class PersistenceToolsHelper

java.lang.Object

com.tangosol.coherence.dslquery.internal.PersistenceToolsHelper

public class PersistenceToolsHelper
extends Object

Various helper classes to support calling Persistence operations from within CohQL.

Since:

12.2.1

Author:

tam 2014.02.14

Field Summary

Fields

Modifier and Type	Field and Description
static String	ARCHIVE_SNAPSHOT JMX operation to archive a snapshot
static String	CREATE_SNAPSHOT JMX operation to create a snapshot.
static String	FORCE_RECOVERY JMX operation to force recovery.
static String	RECOVER_SNAPSHOT JMX operation to recover a snapshot.
static String	REMOVE_ARCHIVED_SNAPSHOT JMX operation to remove an archived snapshot
static String	REMOVE_SNAPSHOT JMX operation to remove a snapshot.
static String	RESUME_SERVICE JMX operation to resume a service.
static String	RETRIEVE_ARCHIVED_SNAPSHOT JMX operation to retrieve an archived snapshot
static String	SUSPEND_SERVICE JMX operation to suspend a service.

Constructor Summary

Constructors

Constructor and Description
PersistenceToolsHelper() Construct a new PersistenceToolsHelper which can be used to issue persistence related commands from CohQL.
PersistenceToolsHelper(PrintWriter out) Construct a new PersistenceToolsHelper which can be used to issue persistence related commands from CohQL.

Method Summary

Modifier and Type	Method and Description
boolean	archivedSnapshotExists(String sServiceName, String sSnapshotName) Validate that an archived snapshot exists for a given service.
static CohQLException	ensureCohQLException(Throwable eCause, String sMsg) Return a CohQLException with the given cause.
static PersistenceToolsHelper	ensurePersistenceToolsHelper(ExecutionContext ctx) Ensure a PersistenceToolsHelper exists within the CohQL ExecutionContext which can be used to issue cluster related Persistence commands.
void	ensureReady(boolean fWait, String sServiceToCheck) Ensures that the specified service is in a ready state to begin snapshot operations.
void	ensureReady(ExecutionContext ctx, String sService) Ensures that the services are in a ready state to begin snapshot operations.
String	getArchiver(String sServiceName) Return the archiver configured for the given service.
static Term	getNextTerm(OPScanner s, String sName, String sDescription, String sCommand) Return a term for a given scanner representing the specified name.
String	getOperationStatus(String sServiceName)
String	getPersistenceMBean(String sServiceName) Return the PersistenceManager MBean name.
String	getServiceMBean(String sServiceName, Member member) Return the Service MBean name.
static File	getSnapshotDirectory(ConfigurableCacheFactory ccf, String sSnapshot, String sServiceName) Return the snapshot directory for a given service and snapshot.
void	invokeOperation(String sOperation, String sServiceName, Object[] aoParams, String[] asParamTypes) Invoke an operation against a PersistenceManagerMBean associated to the given service name.
void	invokeOperationWithWait(String sOperation, String sSnapshot, String sServiceName) Issue an operation and wait for the operation to be complete by polling the "Idle" attribute of the PersistenceCoordinator for the service.
boolean	isTraceEnabled() Return if trace is enabled.
Map<String,String[]>	listArchivedSnapshots() List the archived snapshots for all services.
String[]	listArchivedSnapshots(String sServiceName) Return a list of archived snapshots for a given service.
Map<String,String[]>	listServices() List all the services configured for active or on-demand mode and information about them including: persistence-mode, QuorumStatus and current operation status from the PersistenceSnapshotMBean.
List<String>	listServicesEnvironment() List all the services configured for active or on-demand mode and display the persistence environment implementation.
Map<String,String[]>	listSnapshots() List the snapshots for all services.
String[]	listSnapshots(String sServiceName) List the snapshots for the specified service.
void	resumeService(String sServiceName) Resume a given service.
boolean	serviceExists(String sServiceName) Validate that a service name exists for the current cluster.
void	setPrintWriter(PrintWriter out) Set the PrintWriter for any messages to go to.
boolean	snapshotExists(String sServiceName, String sSnapshotName) Validate that a snapshot exists for a given service.
void	suspendService(String sServiceName) Suspend a given service.
void	validateArchivedSnapshotExistsForAllServices(String sSnapshotName) Validate that an archived snapshot exists across all services to ensure success for a retrieve or purge operation.
void	validateSnapshotExistsForAllServices(String sSnapshotName) Validate that a snapshot exists across all services.

Methods inherited from class java.lang.Object

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

Field Detail

CREATE_SNAPSHOT

public static final String CREATE_SNAPSHOT

JMX operation to create a snapshot.

See Also:

Constant Field Values

RECOVER_SNAPSHOT

public static final String RECOVER_SNAPSHOT

JMX operation to recover a snapshot.

See Also:

Constant Field Values

REMOVE_SNAPSHOT

public static final String REMOVE_SNAPSHOT

JMX operation to remove a snapshot.

See Also:

Constant Field Values

ARCHIVE_SNAPSHOT

public static final String ARCHIVE_SNAPSHOT

JMX operation to archive a snapshot

See Also:

Constant Field Values

RETRIEVE_ARCHIVED_SNAPSHOT

public static final String RETRIEVE_ARCHIVED_SNAPSHOT

JMX operation to retrieve an archived snapshot

See Also:

Constant Field Values

REMOVE_ARCHIVED_SNAPSHOT

public static final String REMOVE_ARCHIVED_SNAPSHOT

JMX operation to remove an archived snapshot

See Also:

Constant Field Values

SUSPEND_SERVICE

public static final String SUSPEND_SERVICE

JMX operation to suspend a service.

See Also:

Constant Field Values

RESUME_SERVICE

public static final String RESUME_SERVICE

JMX operation to resume a service.

See Also:

Constant Field Values

FORCE_RECOVERY

public static final String FORCE_RECOVERY

JMX operation to force recovery.

See Also:

Constant Field Values

Constructor Detail

PersistenceToolsHelper

public PersistenceToolsHelper()

Construct a new PersistenceToolsHelper which can be used to issue persistence related commands from CohQL. No-args constructor is used when no tracing is required.

PersistenceToolsHelper

public PersistenceToolsHelper(PrintWriter out)

Construct a new PersistenceToolsHelper which can be used to issue persistence related commands from CohQL.

Parameters:

out - the PrintWriter to write trace messages to

Method Detail

ensurePersistenceToolsHelper

public static PersistenceToolsHelper ensurePersistenceToolsHelper(ExecutionContext ctx)
                                                           throws CohQLException

Ensure a PersistenceToolsHelper exists within the CohQL ExecutionContext which can be used to issue cluster related Persistence commands. If it doesn't, then create a new one.

Parameters:

ctx - current CohQL ExecutionContext

Returns:

the existing PersistenceToolsHelper or a new one if doesn't exist

Throws:

CohQLException - if we are unable to retrieve a new API

invokeOperationWithWait

public void invokeOperationWithWait(String sOperation,
                                    String sSnapshot,
                                    String sServiceName)
                             throws MBeanException

Issue an operation and wait for the operation to be complete by polling the "Idle" attribute of the PersistenceCoordinator for the service. This method will poll continuously until an "Idle" status has been reached or until timeout set by a calling thread has been raised. e.g.

 try (Timeout t = Timeout.after(120, TimeUnit.SECONDS))
     {
     helper.invokeOperationWithWait("createSnapshot", "snapshot", "Service");
     }
 

When called from CohQL, the TIMEOUT value set in CohQL will be used to interrupt the operation if it has not completed.
Note: Even though and exception is raised, the MBean operation will still execute to completion, but CohQL will return immediately without waiting.

Parameters:

sOperation - the operation to execute

sSnapshot - the snapshot name

sServiceName - the name of the service to execute operation on

Throws:

MBeanException - if any MBean related errors

invokeOperation

public void invokeOperation(String sOperation,
                            String sServiceName,
                            Object[] aoParams,
                            String[] asParamTypes)
                     throws MBeanException

Invoke an operation against a PersistenceManagerMBean associated to the given service name.

Parameters:

sOperation - the operation to execute

sServiceName - the name of the service to execute operation on

aoParams - the parameters of the operation

asParamTypes - the parameter types of the operation

Throws:

MBeanException - if an error occurred invoking the MBean

serviceExists

public boolean serviceExists(String sServiceName)

Validate that a service name exists for the current cluster.

Parameters:

sServiceName - the service name to check

Returns:

true if the service exists

snapshotExists

public boolean snapshotExists(String sServiceName,
                              String sSnapshotName)

Validate that a snapshot exists for a given service.

Parameters:

sServiceName - the service name to check

sSnapshotName - the snapshot name to check

Returns:

true if the snapshot exists for the service

archivedSnapshotExists

public boolean archivedSnapshotExists(String sServiceName,
                                      String sSnapshotName)

Validate that an archived snapshot exists for a given service.

Parameters:

sServiceName - the service name to check

sSnapshotName - the archived snapshot name to check

Returns:

true if the archived snapshot exists for the service

validateSnapshotExistsForAllServices

public void validateSnapshotExistsForAllServices(String sSnapshotName)

Validate that a snapshot exists across all services.

Parameters:

sSnapshotName - the snapshot name to check

Throws:

CohQLException - if the condition is not met

validateArchivedSnapshotExistsForAllServices

public void validateArchivedSnapshotExistsForAllServices(String sSnapshotName)

Validate that an archived snapshot exists across all services to ensure success for a retrieve or purge operation.

Parameters:

sSnapshotName - the archived snapshot name to check

Throws:

CohQLException - if the condition is met

listServices

public Map<String,String[]> listServices()

List all the services configured for active or on-demand mode and information about them including: persistence-mode, QuorumStatus and current operation status from the PersistenceSnapshotMBean.

Returns:

a Map of services and related information

listServicesEnvironment

public List<String> listServicesEnvironment()

List all the services configured for active or on-demand mode and display the persistence environment implementation.

Returns:

a List of services and related information

listSnapshots

public String[] listSnapshots(String sServiceName)

List the snapshots for the specified service.

Parameters:

sServiceName - the name of the service to list snapshots for

Returns:

the snapshots for the specified service or an empty String[] if none exist

listSnapshots

public Map<String,String[]> listSnapshots()

List the snapshots for all services.

Returns:

a Map of services and their snapshots.

listArchivedSnapshots

public String[] listArchivedSnapshots(String sServiceName)

Return a list of archived snapshots for a given service.

Parameters:

sServiceName - the name of the service to query

Returns:

a String[] of archived snapshots for the given service

listArchivedSnapshots

public Map<String,String[]> listArchivedSnapshots()

List the archived snapshots for all services.

Returns:

a Map of services and their archived snapshots.

getArchiver

public String getArchiver(String sServiceName)

Return the archiver configured for the given service.

Parameters:

sServiceName - the name of the service to query

Returns:

the archiver configured for the given services or 'n/a' if none exists

resumeService

public void resumeService(String sServiceName)

Resume a given service.

Parameters:

sServiceName - the service to resume

suspendService

public void suspendService(String sServiceName)

Suspend a given service.

Parameters:

sServiceName - the service to suspend

ensureReady

public void ensureReady(boolean fWait,
                        String sServiceToCheck)

Ensures that the specified service is in a ready state to begin snapshot operations. Ie. The service should not have operations that are running. This call will wait for any processes to complete if fWait is true.
This method will poll continuously until an "Idle" status has been reached or until timeout set by a calling thread has been raised.

Parameters:

fWait - if true and the service is not Idle then wait, otherwise throw an exception

sServiceToCheck - the service to check for or null for all services

Throws:

CohQLException - if any services are not in a proper state

ensureReady

public void ensureReady(ExecutionContext ctx,
                        String sService)

Ensures that the services are in a ready state to begin snapshot operations. Ie. they should not have operations that are running. If the context is silent then we will wait, otherwise will fail fast.

Parameters:

ctx - context

sService - the service to wait to be ready or if null, then all services

Throws:

CohQLException - if any services are not in a proper state

ensureCohQLException

public static CohQLException ensureCohQLException(Throwable eCause,
                                                  String sMsg)

Return a CohQLException with the given cause. If the specified cause is an instance of CohQLException, the given throwable will be returned as is; otherwise, a new CohQLException will be allocated and returned.

Parameters:

eCause - an optional cause

sMsg - an optional detail message

Returns:

a CohQLException with the given cause and detail message

getOperationStatus

public String getOperationStatus(String sServiceName)

getPersistenceMBean

public String getPersistenceMBean(String sServiceName)

Return the PersistenceManager MBean name.

Parameters:

sServiceName - the name of the service to return the name for

Returns:

the MBean name

getServiceMBean

public String getServiceMBean(String sServiceName,
                              Member member)

Return the Service MBean name.

Parameters:

sServiceName - the name of the service to return the name for

member - the member of the service to return the name for

Returns:

the MBean name

getNextTerm

public static Term getNextTerm(OPScanner s,
                               String sName,
                               String sDescription,
                               String sCommand)

Return a term for a given scanner representing the specified name. If the end of statement is reached then an CohQLException is raised.

Parameters:

s - OPScanner to use

sName - the name to assign the new term

sDescription - a description for any exception

sCommand - the command name

Returns:

a new term

Throws:

CohQLException - if end of statement is reached

getSnapshotDirectory

public static File getSnapshotDirectory(ConfigurableCacheFactory ccf,
                                        String sSnapshot,
                                        String sServiceName)

Return the snapshot directory for a given service and snapshot.

Parameters:

ccf - ConfigurableCacheFactory to use to get dependencies

sSnapshot - the snapshot name to use

sServiceName - the service name to use

Returns:

a File representing the snapshot directory

setPrintWriter

public void setPrintWriter(PrintWriter out)

Set the PrintWriter for any messages to go to.

Parameters:

out - the PrintWriter to use

isTraceEnabled

public boolean isTraceEnabled()

Return if trace is enabled.

Returns:

if trace is enabled