cvs commit: jakarta-avalon/src/proposal/profile Profilable.java Profiler.java

[bl...@apache.org]

bloritsch    01/12/12 06:57:09

  Added:       src/proposal/profile Profilable.java Profiler.java
  Log:
  New proposed interfaces for Framework
  
  Revision  Changes    Path
  1.1                  jakarta-avalon/src/proposal/profile/Profilable.java
  
  Index: Profilable.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.avalon.framework.profile;
  
  /**
   * The Profilable interface is to mark objects that can be sampled by a Profiler.
   * The interface only has one method to simplify the items that can be sampled.
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   */
  interface Profilable
  {
      /**
       * Obtain the sample.  All samples are an integer, so the profiled objects
       * must measure quantity (numbers of items), rate (items/period), time in
       * milliseconds, etc.
       */
      int getSample();
  }
  
  
  1.1                  jakarta-avalon/src/proposal/profile/Profiler.java
  
  Index: Profiler.java
  ===================================================================
  /*
   * Copyright (C) The Apache Software Foundation. All rights reserved.
   *
   * This software is published under the terms of the Apache Software License
   * version 1.1, a copy of which has been included with this distribution in
   * the LICENSE.txt file.
   */
  package org.apache.avalon.framework.profile;
  
  import java.io.File;
  import java.io.IOException;
  
  /**
   * The Profiler is used to determine numeric values for specific parts of the
   * Avalon environment.  The idea is to add references to Profilable objects to
   * the Profiler.  The Profiler takes periodic snapshots of the running system
   * so that performance or resource usage can be assertained.  The sample duration
   * is dependant on the Profiler's settings, and should never change during the
   * time the Profiler is running.
   *
   * @author <a href="mailto:bloritsch@apache.org">Berin Loritsch</a>
   */
  public interface Profiler
  {
      /**
       * Tests wether the Profiler is active for the system.
       *
       * @returns <code>true</code> if Profiler is on, <code>false</code> if it is off.
       */
      boolean isRunning();
  
      /**
       * Adds a target to profile, along with a name for the target.  Good names
       * include what the expected samples are.  For instance "ThreadController:
       * number of threads" or "EventQueue: events processed per second".  The real
       * results come from the Profilable object itself, but the name is so humans
       * have a reference for the values.
       *
       * @parameter  name           The name of the sample type
       * @parameter  profileSource  The actual source of the samples
       */
      void add( String name, Profilable profileSource );
  
      /**
       * Serializes the results of the profiling to a file.  The actual format
       * depends on the Profiler in use.  It can be simple Comma Separated Values
       * (CSV) with the columns representing a unique Profilable.  Most spreadsheet
       * programs can import this and generate meaningful graphs from it.  Another
       * alternative is to output the information in a tool specific format.  The
       * actual format depends on the Profiler in question, and the Profiler merely
       * needs the reference to the output file.
       *
       * @parameter  outputInfo  The handle of the file the profiler serializes the
       *                         results to.
       *
       * @throws <code>IOException</code> If the file is not valid, or cannot be
       *         written to.
       */
      void serialize( File outputInfo ) throws IOException;
  }
  
  
  

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>