avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/instrument/src/xdocs instrumentables.xml index.xml menu.xml
Date Mon, 29 Jul 2002 18:45:09 GMT
bloritsch    2002/07/29 11:45:09

  Modified:    instrument build.xml
               instrument/example build.xml
               instrument/src/xdocs index.xml menu.xml
  Added:       instrument/example default.properties
               instrument/src/xdocs instrumentables.xml
  Log:
  add some meaningful documentation
  
  Revision  Changes    Path
  1.28      +1 -31     jakarta-avalon-excalibur/instrument/build.xml
  
  Index: build.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/instrument/build.xml,v
  retrieving revision 1.27
  retrieving revision 1.28
  diff -u -r1.27 -r1.28
  --- build.xml	29 Jul 2002 16:51:10 -0000	1.27
  +++ build.xml	29 Jul 2002 18:45:08 -0000	1.28
  @@ -466,37 +466,7 @@
         <mkdir dir="${build.dir}/work"/>
   
         <!-- Base pointers for non-xdocs documentation. Override these in .ant.properties
to link to local docs -->
  -      <copy todir="${build.context}" filtering="on">
  -        <fileset dir="${context.dir}">
  -          <exclude name="diagrams/**"/>
  -          <exclude name="resources/**"/>
  -          <exclude name="xdocs"/>
  -        </fileset>
  -      </copy>
  -
  -      <copy todir="${build.context}/xdocs" filtering="on" overwrite="yes">
  -        <fileset dir="${xdocs.dir}"/>
  -      </copy>
  -
  -      <copy todir="${build.context}/resources" filtering="off" overwrite="yes">
  -        <fileset dir="${context.dir}/resources"/>
  -        <fileset dir="${xdocs.dir}">
  -          <include name="**/images/**"/>
  -        </fileset>
  -      </copy>
  -
  -      <java classname="org.apache.cocoon.Main" fork="true">
  -        <arg value="-c${build.context}/"/>
  -        <arg value="-d${build.docs}"/>
  -        <arg value="-w${build.dir}/work"/>
  -        <arg value="-l${build.dir}/work/cocoon.log"/>
  -        <arg value="-uINFO"/>
  -        <arg value="-f${xdocs.dir}/${dir-name}.uris"/>
  -        <classpath>
  -          <path refid="tools.class.path"/>
  -          <fileset dir="${tools.dir}/ext"/>
  -        </classpath>
  -      </java>
  +      <ant antfile="../cocoonbuild.xml"/>
   
         <copy todir="${docs.dir}">
           <fileset dir="${build.docs}">
  
  
  
  1.2       +14 -12    jakarta-avalon-excalibur/instrument/example/build.xml
  
  Index: build.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/instrument/example/build.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- build.xml	29 Jul 2002 16:05:18 -0000	1.1
  +++ build.xml	29 Jul 2002 18:45:08 -0000	1.2
  @@ -6,6 +6,7 @@
   
   <project name="instrument-manager-example" default="main" basedir=".">
   
  +    <property name="avalon-framework.home" value="${basedir}/../../../jakarta-avalon"/>
       <!--
         Give user a chance to override without editing this file
         (and without typing -D each time he compiles it)
  @@ -13,6 +14,7 @@
       <property file="ant.properties"/>
       <property file="../ant.properties"/>
       <property file="${user.home}/.ant.properties"/>
  +    <property file="default.properties"/>
   
       <!-- Directories build by ant -->
       <property name="build.dir"             value="${basedir}/build"/>
  @@ -48,47 +50,47 @@
       <target name="collect-jars">
           <!-- Xerces -->
           <copy file="${xerces.jar}" todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- XML-APIs -->
           <copy file="${xml-apis.jar}" todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Xalan -->
           <copy file="${xalan.jar}" todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Logkit -->
           <copy file="${logkit.jar}" todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Framework -->
           <copy file="${avalon-framework.jar}" todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Concurrent -->
           <copy file="${excalibur-concurrent.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Collections -->
           <copy file="${excalibur-collections.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Component -->
           <copy file="${excalibur-component.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Logger -->
           <copy file="${excalibur-logger.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Pool -->
           <copy file="${excalibur-pool.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Instrument -->
           <copy file="${excalibur-instrument.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Avalon Excalibur Instrument Manager -->
           <copy file="../build/lib/excalibur-instrument-manager-0.1.jar"
               todir="${lib.dir}" preservelastmodified="yes"/>
  -        
  +
           <!-- Altrmi Jars -->
           <copy file="${excalibur-altrmi-common.jar}"
               todir="${lib.dir}" preservelastmodified="yes"/>
  
  
  
  1.1                  jakarta-avalon-excalibur/instrument/example/default.properties
  
  Index: default.properties
  ===================================================================
  # -------------------------------------------------------------------
  # B U I L D  P R O P E R T I E S
  # -------------------------------------------------------------------
  # Specifies default property values
  # Overridden by ../default.properties and all ant.properties
  # Not user-editable; use ant.properties files instead
  
  name=excalibur-instrument
  client.name=${name}-client
  manager.name=${name}-manager
  Name=Excalibur Instrument
  dir-name=instrument
  version=0.2
  package-version=0.2
  year=2002
  
  # --------------------------------------------------
  #                REQUIRED LIBRARIES
  # --------------------------------------------------
  # None
  
  tools.dir=${avalon-framework.home}/tools
  
  # --------------------------------------------------
  #                OPTIONAL LIBRARIES
  # --------------------------------------------------
  
  # ----- Avalon Framework, version 4.1 or later -----
  avalon-framework.home=${basedir}/../../jakarta-avalon
  avalon-framework.lib=${avalon-framework.home}/build/lib
  avalon-framework.jar=${avalon-framework.lib}/avalon-framework.jar
  
  # ----- Logkit -----
  logkit.home=${basedir}/../../jakarta-avalon-logkit
  logkit.lib=${logkit.home}/build/lib
  logkit.jar=${logkit.lib}/logkit.jar
  
  # ----- Altrmi -----
  excalibur-altrmi.home=${basedir}/../altrmi/dist
  excalibur-altrmi-common.jar=${excalibur-altrmi.home}/excalibur-altrmi-common.jar
  excalibur-altrmi-server-impl.jar=${excalibur-altrmi.home}/excalibur-altrmi-server-impl.jar
  excalibur-altrmi-server-interfaces.jar=${excalibur-altrmi.home}/excalibur-altrmi-server-interfaces.jar
  excalibur-altrmi-client-impl.jar=${excalibur-altrmi.home}/excalibur-altrmi-client-impl.jar
  excalibur-altrmi-client-interfaces.jar=${excalibur-altrmi.home}/excalibur-altrmi-client-interfaces.jar
  excalibur-altrmi-generator.jar=${excalibur-altrmi.home}/excalibur-altrmi-generator.jar
  
  xerces.jar=${tools.dir}/lib/xerces-2.0.1.jar
  xml-apis.jar=${tools.dir}/lib/xml-apis.jar
  xalan.jar=${tools.dir}/lib/xalan-2.3.1.jar
  
  # --------------------------------------------------
  
  
  #  Settings used to configure compile environment
  build.debug = on
  build.optimize = off
  build.deprecation = off
  build.compress = false
  junit.failonerror = false
  
  #  location of intermediate products
  build.dir = ${basedir}/build
  build.testsrc = ${build.dir}/testsrc
  build.testclasses = ${build.dir}/testclasses
  build.lib = ${build.dir}/lib
  build.conf = ${build.dir}/conf
  build.classes = ${build.dir}/classes
  build.client.classes = ${build.dir}/clientclasses
  build.manager.classes = ${build.dir}/managerclasses
  build.tests = ${build.dir}/tests
  build.reports = ${build.dir}/reports
  build.genjava="${build.dir}/genjava
  
  #  Set the properties for source directories
  src.dir = ${basedir}/src
  java.dir = ${src.dir}/java
  conf.dir = ${src.dir}/conf
  test.dir = ${src.dir}/test
  manager.dir = ${src.dir}/manager
  client.dir = ${src.dir}/client
  
  #  needed by Cocoon
  build.context = ${build.dir}/documentation
  build.docs = ${build.dir}/docs
  build.xdocs = ${build.dir}/xdocs
  context.dir = ../../jakarta-avalon/src/documentation
  tools.dir = ../../jakarta-avalon/tools
  tools.jar = ${java.home}/../lib/tools.jar
  docs.dir = docs
  xdocs.dir = ${src.dir}/xdocs
  
  #  Set the properties for distribution directories
  dist.dir = ${basedir}/dist
  dist.javadocs = ${dist.dir}/docs/api
  
  #  name of .zip/.tar.gz/.bz2 files and their top-level directory
  dist.name = ${name}-${version}
  
  #  name of jar file
  jar.name = ${name}-${version}.jar
  client.jar.name = ${client.name}-${version}.jar
  manager.jar.name = ${manager.name}-${version}.jar
  
  #  property indicating directory where all distribution archives are placed
  dist.base = distributions
  
  depchecker.prefix=.
  
  
  
  
  1.2       +24 -11    jakarta-avalon-excalibur/instrument/src/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/instrument/src/xdocs/index.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- index.xml	17 Jul 2002 21:11:36 -0000	1.1
  +++ index.xml	29 Jul 2002 18:45:09 -0000	1.2
  @@ -1,15 +1,28 @@
   <?xml version="1.0"?>
   
   <document>
  -    <properties>
  -        <title>Excalibur ??? - Overview</title>
  -        <author email="???">???</author>
  -    </properties>
  -    <body>
  -        <section name="Introduction">
  -            <p>
  -                Blah!
  -            </p>
  -        </section>
  -    </body>
  +  <header>
  +    <title>Excalibur Instrument - Overview</title>
  +    <authors>
  +      <person name="Berin Loritsch" email="bloritsch@apache.org"/>
  +    </authors>
  +  </header>
  +  <body>
  +    <s1 title="Introduction">
  +      <p>
  +        Excalibur Instrument is an instrumentation utility that allows you
  +        to attach a separate JVM to your running application to determine its
  +        health.  Instrumentation is the process of exposing the internal state
  +        in a way that is easy for an administrator or help desk personell to
  +        digest.  Excalibur Instrumentation is such a package that you can use
  +        for your Avalon based projects.
  +      </p>
  +      <p>
  +        In order to use this in your projects, you need to set up your project
  +        using an Instrument aware container (<link href="../fortress/">Fortress</link>
  +        is one of them), and set up your components according to the specifications
  +        <link href="instrumentables.html">here</link>.
  +      </p>
  +    </s1>
  +  </body>
   </document>
  
  
  
  1.2       +5 -3      jakarta-avalon-excalibur/instrument/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/instrument/src/xdocs/menu.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- menu.xml	19 Jul 2002 16:24:40 -0000	1.1
  +++ menu.xml	29 Jul 2002 18:45:09 -0000	1.2
  @@ -1,14 +1,16 @@
   <?xml version="1.0" encoding="UTF-8"?>
   <project
  -	href="http://jakarta.apache.org/avalon/excalibur/instrument/"
  +    href="http://jakarta.apache.org/avalon/excalibur/instrument/"
       name="Excalibur Instrument">
   
       <title>Excalibur Instrument</title>
       <body>
  -        <item href="/../index.html" name="Back to Excalibur"/>
  +        <menu name="Related">
  +          <item href="../fortress/" name="Excalibur Fortress"/>
  +        </menu>
           <menu name="About">
               <item name="Overview" href="index.html"/>
  -            <item name="Excalibur Home" href="http://jakarta.apache.org/avalon/excalibur/index.html"/>
  +            <item name="Enabling Instrumentation" href="instrumentables.html"/>
               <item name="Download" href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release/???"/>
               <item name="API Docs" href="api/"/>
           </menu>
  
  
  
  1.1                  jakarta-avalon-excalibur/instrument/src/xdocs/instrumentables.xml
  
  Index: instrumentables.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Excalibur Instrument - Enable Instrumenting</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="Coding for Instrumentation">
        <p>
          There are different types of instrumentation we need to use, depending
          on our purposes.  Excalibur Instrument has two basic types:
          <code>CounterInstrument</code> and <code>ValueInstrument</code>.
 The
          <code>CounterInstrument</code> allows us to take samples that represent
          a count of events.  The <code>ValueInstrument</code> allows you to take
          samples that represent the current value.
        </p>
        <p>
          Excalibur Instrument knows how to take the raw samples, and bring them
          in line with more useable numbers.  It is not uncommon to want an average
          value, a maximum value, or a minimum value for each sample period.  You
          do not have to do anything in your code to explicitly do that.
        </p>
      </s1>
      <s1 title="Getting Started">
        <p>
          You will need to import the relavant classes from the avalon-instrument.jar
          file.
        </p>
        <source>
  <![CDATA[
  import org.apache.excalibur.instrument.CounterInstrument;
  import org.apache.excalibur.instrument.Instrumentable;
  import org.apache.excalibur.instrument.Instrument;
  import org.apache.excalibur.instrument.ValueInstrument;
  ]]>
        </source>
        <p>
          Once you do that, you need to implement the <code>Instrumentable</code>
          interface, and set up your instrumentation points.  The InstrumentManager,
          or the parent Instrumentable will assign the name to your Instrumentable.
          That way we can easily determine what the heirarchy is.
        </p>
        <source>
  <![CDATA[
  public class DefaultExampleInstrumentable
      implements Instrumentable
  {
      public static final String INSTRUMENT_VALUE_NAME   = "value";
      public static final String INSTRUMENT_COUNTER_NAME = "counter";
  
      /** Instrumentable Name assigned to this Instrumentable */
      private String m_instrumentableName;
  
      /** Instrument used to profile values */
      private ValueInstrument m_valueInstrument = new ValueInstrument( INSTRUMENT_VALUE_NAME
);
  
      /** Instrument used to profile a count of actions. */
      private CounterInstrument m_counterInstrument = new CounterInstrument( INSTRUMENT_COUNTER_VALUE
);
  
      /*---------------------------------------------------------------
       * Constructors
       *-------------------------------------------------------------*/
      public DefaultExampleInstrumentable()
      {}
  
      // Skip a bunch of other stuff....
  
      /*---------------------------------------------------------------
       * Instrumentable Methods
       *-------------------------------------------------------------*/
      /**
       * Sets the name for the Instrumentable.  The Instrumentable Name is used
       *  to uniquely identify the Instrumentable during the configuration of
       *  the InstrumentManager and to gain access to an InstrumentableDescriptor
       *  through the InstrumentManager.  The value should be a string which does
       *  not contain spaces or periods.
       * <p>
       * This value may be set by a parent Instrumentable, or by the
       *  InstrumentManager using the value of the 'instrumentable' attribute in
       *  the configuration of the component.
       *
       * @param name The name used to identify a Instrumentable.
       */
      public void setInstrumentableName( String name )
      {
          m_instrumentableName = name;
      }
  
      /**
       * Gets the name of the Instrumentable.
       *
       * @return The name used to identify a Instrumentable.
       */
      public String getInstrumentableName()
      {
          return m_instrumentableName;
      }
  
      /**
       * Obtain a reference to all the Instruments that the Instrumentable object
       *  wishes to expose.  All sampling is done directly through the
       *  Instruments as opposed to the Instrumentable interface.
       *
       * @return An array of the Instruments available for profiling.  Should
       *         never be null.  If there are no Instruments, then
       *         EMPTY_INSTRUMENT_ARRAY can be returned.  This should never be
       *         the case though unless there are child Instrumentables with
       *         Instruments.
       */
      public Instrument[] getInstruments()
      {
          return new Instrument[]
          {
              m_valueInstrument,
              m_counterInstrument
          };
      }
  
      /**
       * Any Object which implements Instrumentable can also make use of other
       *  Instrumentable child objects.  This method is used to tell the
       *  InstrumentManager about them.
       *
       * @return An array of child Instrumentables.  This method should never
       *         return null.  If there are no child Instrumentables, then
       *         EMPTY_INSTRUMENTABLE_ARRAY can be returned.
       */
      public Instrumentable[] getChildInstrumentables()
      {
          // This instrumentable does not have any children.
          return Instrumentable.EMPTY_INSTRUMENTABLE_ARRAY;
      }
  }
  ]]>
        </source>
      </s1>
      <s1 title="Using Instruments">
        <p>
          Lastly, you need to use your instrumentables.  Excalibur Instrument will
          skip the sampling and processing of values if no Manager or Client is
          attached to them.
        </p>
        <source>
  <![CDATA[
  /**
   * Method that uses the instrumentables we have set up so far
   */
  Object lookup(String name)
  {
      // Do critical stuff
      m_valueInstrument.setValue( m_dictionary.size() );
      m_counterInstrument.increment();
  
      return m_dictionary.get( name );
  }
  ]]>
        </source>
      </s1>
    </body>
  </document>
  
  
  

--
To unsubscribe, e-mail:   <mailto:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message