com.gemstone.gemfire.cache.query.CqQuery Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of gemfire-core Show documentation
SnappyData store based off Pivotal GemFireXD
There is a newer version: 2.0-BETA
/*
 * Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you
 * may not use this file except in compliance with the License. You
 * may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * permissions and limitations under the License. See accompanying
 * LICENSE file.
 */

package com.gemstone.gemfire.cache.query;


/**
 * Interface for continuous query. This provides methods for managing a CQ 
 * once it is created through the QueryService. 
 * The methods allow you to retrieve CQ related information, operate on CQ
 * like execute, stop, close and get the state of the CQ.
 *
 * @author      Rao Madduri
 * @since 5.5
 */

public interface CqQuery {

  /**
   * Get the original query string that was specified with CQ.
   * @return String the query string associated with CQ.
   */
  public String getQueryString();

  /**
   * Get the query object generated for this CQs query.
   * @return Query query object for the query string.
   */
  public Query getQuery();

  /**
   * Get the name of the CQ.
   * @return the name of the CQ.
   */
  public String getName();

  /**
   * Get statistics information for this CQ.
   * @return CqStatistics CQ statistics object.
   */
  public CqStatistics getStatistics();  

  /**
   * Get CqAttributes for this CQ.
   * @see CqAttributes
   * @return CqAttributes cqAttribute set with this CqQuery.
   */
  public CqAttributes getCqAttributes(); 

  /**
   * Get CqAttributesMutator for this CQ.
   * @see CqAttributesMutator
   * @return CqAttributesMutator.
   */
  public CqAttributesMutator getCqAttributesMutator(); 

  /**
   * Starts executing the CQ or, if the CQ is in a stopped state, resumes 
   * execution. Gets the current resultset for the CQ query. The CQ is 
   * executed on the primary server, and then redundant servers as needed. 
   * If execution fails on all servers, a CqException is thrown. 
   * If the query is complex and the data set is large, this execution may 
   * take a long time, which may cause a socket read timeout in the client. 
   * To allow adequate time, you may need to set a longer pool read-timeout 
   * in the client.      
   * @throws CqClosedException if this CqQuery is closed.
   * @throws RegionNotFoundException if the specified region in the 
   *         query string is not found.
   * @throws IllegalStateException if the CqQuery is in the RUNNING state
   *         already.
   * @throws CqException if failed to execute and get initial results.
   * @return SelectResults resultset obtained by executing the query.
   */
  public  CqResults executeWithInitialResults() throws CqClosedException, RegionNotFoundException, CqException;

  /**
   * Start executing the CQ or if this CQ is stopped earlier, resumes execution of the CQ.
   * The CQ is executed on primary and redundant servers, if CQ execution fails on all the 
   * server then a CqException is thrown.
   * @throws CqClosedException if this CqQuery is closed.
   * @throws RegionNotFoundException if the specified region in the
   *         query string is not found.
   * @throws IllegalStateException if the CqQuery is in the RUNNING state
   *         already.
   * @throws CqException if failed to execute.
   */
  public void execute() throws CqClosedException, RegionNotFoundException, CqException;

  /**
   *  Stops this CqQuery without releasing resources. Puts the CqQuery into
   *  the STOPPED state. Can be resumed by calling execute or
   *  executeWithInitialResults.
   *  @throws IllegalStateException if the CqQuery is in the STOPPED state
   *          already.
   *  @throws CqClosedException if the CQ is CLOSED.
   */
  public void stop() throws CqClosedException, CqException;

  /**
   * Get the state of the CQ in CqState object form. 
   * CqState supports methods like isClosed(), isRunning(), isStopped().
   * @see CqState
   * @return CqState state object of the CQ.
   */ 
  public CqState getState();

  /**
   * Close the CQ and stop execution.  
   * Releases the resources associated with this CqQuery.
   * @throws CqClosedException Further calls on this CqQuery instance except 
   *         for getState() or getName().
   * @throws CqException - if failure during cleanup of CQ resources.
   */ 
  public void close() throws CqClosedException, CqException;

  /**
   * This allows to check if the CQ is in running or active.
   * @return boolean true if running, false otherwise
   */
  public boolean isRunning();

  /**
   * This allows to check if the CQ is in stopped.
   * @return boolean true if stopped, false otherwise
   */ 
  public boolean isStopped();

  /**
   * This allows to check if the CQ is closed.
   * @return boolean true if closed, false otherwise
   */
  public boolean isClosed();
  
  /**
   * This allows to check if the CQ is durable.
   * @return boolean true if durable, false otherwise
   * @since 5.5
   */
  public boolean isDurable();

}