utils/streamscope/src/main/java/org/apache/edgent/streamscope/mbeans/StreamScopeMXBean.java

/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you 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.
*/
package org.apache.edgent.streamscope.mbeans;

import java.util.concurrent.TimeUnit;

/**
 * A Stream "oscilloscope" for capturing stream tuples for analysis / debug.
 * @see StreamScopeRegistryMXBean
 */
public interface StreamScopeMXBean {
  
  /**
   * TYPE is used to identify this bean as a StreamScope bean when building the bean's {@code ObjectName}.
   * The value is {@value} 
   */
  public static String TYPE = "streamScope";
  
  /**
   * Is tuple capture enabled?
   * @return true if enabled.
   */
  boolean isEnabled();
  
  /**
   * Enable or disable tuple capture.
   * <P>
   * Disabling releases the capture buffer.
   * </P>
   * @param isEnabled true to enable, false to disable.
   * @see #setPaused(boolean)
   */
  void setEnabled(boolean isEnabled);
  
  /**
   * Is capture paused?
   * @return true if paused
   */
  boolean isPaused();
  
  /**
   * Set capture paused control
   * <P>
   * Pausing doesn't affect the capture buffer's current contents.
   * </P>
   * @param paused true to pause, false to clear pause.
   */
  void setPaused(boolean paused);
  
//No ability for Predicate param w/JMX right?   
///**
// * Set a pause-on predicate.  Capture is paused if the predicate
// * returns true;
// * @param predicate the predicate
// * @see Functions#alwaysFalse()
// */
//void setPauseOn(Predicate<T> predicate);

  /**
   * Get all captured tuples as JSON.
   * <P>
   * The JSON is that generated by {@code Gson.toJson(StreamScope.getSamples())}.
   * </P><P>
   * The JSON is an array of {@link org.apache.edgent.streamscope.StreamScope.Sample Sample} JSON objects.  
   * Each Sample JSON object consists of:
   * <UL>
   * <LI>ts - long. capture timestamp in millis from System.currentTimeMillis()</LI>
   * <LI>nanos - long. capture nanosecond timestamp from System.nanoTime()</LI>
   * <LI>tuple - see below</LI>
   * </UL>
   * The value of the "tuple" property is:
   * <UL>
   * <LI>for a primitive tuple type like String, Numeric or Boolean it's a 
   * JSON string, numeric, or boolean value respectively.</LI>
   * <LI>Arrays or collections are a JSON array of JSON elements for the members.</LI>
   * <LI>For other types it's a JSON object with the type's
   * members and JSON encoding of their values.</LI>
   * </UL>
   * <P>
   * The returned samples are removed from the capture buffer.
   * </P>
   * @return JSON of the captured samples
   */
  String getSamples();

  /**
   * Get the number of Samples currently captured
   * @return the count
   */
  int getSampleCount();

  /**
   * Set the maximum number of tuples to retain.
   * <P>
   * The capture buffer is cleared.
   * </P>
   * @param maxCount the maximum number of tuples to retain.
   *        Specify 0 to disable count based retention.
   */
  void setMaxRetentionCount(int maxCount);
  
  /**
   * Set the maximum retention time of a tuple.
   * <P>
   * The capture buffer is cleared.
   * </P>
   * @param age the amount of time to retain a tuple.
   *        Specify 0 to disable age based retention.
   * @param unit {@link TimeUnit}
   */
  void setMaxRetentionTime(long age, TimeUnit unit);
  
  /**
   * Capture the first and every nth tuple
   * @param count the nth value interval
   */
  void setCaptureByCount(int count);
  
  /**
   * Capture the 1st tuple and then the next tuple after {@code period}
   * {@code unit} time has elapsed since the previous captured tuple.
   * 
   * @param elapsed time to delay until next capture
   * @param unit {@link TimeUnit}
   */
  void setCaptureByTime(long elapsed, TimeUnit unit);

// No ability for Predicate param w/JMX right?   
//  /**
//   * Capture a tuple if the {@code predicate} test of the tuple returns true.
//   * @param predicate
//   */
//  void setCaptureByPredicate(Predicate<T> predicate);
  
}