You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by le...@apache.org on 2002/03/26 12:17:22 UTC
cvs commit: jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument AbstractInstrument.java CounterInstrument.java Instrument.java InstrumentManageable.java InstrumentManager.java InstrumentProxy.java Instrumentable.java ValueInstrument.java
leif 02/03/26 03:17:21
Added: instrument .cvsignore BUILDING.txt README.txt
ant.properties.sample build.xml project.properties
instrument/src/java/org/apache/avalon/excalibur/instrument
AbstractInstrument.java CounterInstrument.java
Instrument.java InstrumentManageable.java
InstrumentManager.java InstrumentProxy.java
Instrumentable.java ValueInstrument.java
Log:
Check in new instrument sub project.
Revision Changes Path
1.1 jakarta-avalon-excalibur/instrument/.cvsignore
Index: .cvsignore
===================================================================
ant.properties
build
checkstyle.cache
distributions
dist
excalibur-*
*.el
*.ipr
1.1 jakarta-avalon-excalibur/instrument/BUILDING.txt
Index: BUILDING.txt
===================================================================
Building The Component
======================
In order to build a binary distribution version of the component from a
source distribution, you must have a Java Development Kit (JDK) for
version 1.1 (or later) downloaded and installed (version 1.3.1
recommended), and do the following:
(0) Download and Install a Java Development Kit
* Download a Java Development Kit (JDK) release (version 1.1 or later)
from:
http://java.sun.com/j2se/
* Install the JDK according to the instructions included with the release.
* Set an environment variable JAVA_HOME to the pathname of the directory
into which you installed the JDK release.
(1) Download and Install the Ant Binary Distribution
* Download a binary distribution of Ant 1.4.1 from:
http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/bin/
On a Windows platform, you will need:
jakarta-ant-1.4.1-bin.zip
jakarta-ant-1.4.1-optional.jar
On a Unix platform, you will need:
jakarta-ant-1.4.1-bin.tar.gz
jakarta-ant-1.4.1-optional.jar
* Unpack the binary distribution into a convenient location so that the
Ant release resides in its own directory (conventionally named
"jakarta-ant-1.4.1"). For the purposes of the remainder of this document,
the symbolic name "${ant.home}" is used to refer to the full pathname of
the release directory.
* Copy the file "jakarta-ant-1.4.1-optional.jar", downloaded above, into
the directory "${ant.home}/lib". This makes available several Ant
extension commands that are commonly required when building Jakarta
based projects.
* Modify the PATH environment variable to include directory
"${ant.home}/bin" in its list. This makes the "ant" command line script
available, which will be used to actually perform the build.
(2) Download and Install the JUnit Testing Package (OPTIONAL)
NOTE: This is only required if you wish to run the unit tests for
this component
* Download the JUnit unit test package (version 3.7 or later) from:
http://www.junit.org/
* Unpack the package into a convenient location so that it resides in its
own subdirectory.
* Copy the file "junit.jar", downloaded above, into the directory
"${ant.home}/lib". This makes available the unit testing tasks that are
commonly required when building Jakarta based projects.
(3) Download and Install the JDepend 2.2, Dependency Analysis Package (OPTIONAL)
NOTE: This is only required if you wish to run dependency analysis for
this component.
* Download the JDepend package (version 2.2 or later) from:
http://www.clarkware.com/software/JDepend.html
* Unpack the package into a convenient location so that it resides in its
own subdirectory.
* Copy the file "jdepend.jar", downloaded above, into the directory
"${ant.home}/lib". This makes available the dependency analysis tasks.
(4) Download and Install Checkstyle, 2.1 or later (OPTIONAL)
NOTE: This is only required if you wish to generate reports regarding code style.
* Download the Checkstyle package (version 2.1 or later) from:
http://checkstyle.sourceforge.net/
* Unpack the package into a convenient location so that it resides in its
own subdirectory.
(5) Download and Install the Xalan, XSLT engine (OPTIONAL)
NOTE: This is only required if you wish to generate reports for the dependency
analysis, checkstyle and unit testing results.
* Download the Xalan package (version 2.3.1 or later) from:
http://xml.apache.org/xalan-j/
* Unpack the package into a convenient location so that it resides in its
own subdirectory.
* Copy the files "xalan.jar", and "xml-apis.jar", downloaded above, into
the directory "${ant.home}/lib". This makes available the XSLT reporting
capabilities.
(6) Customize Build Properties For This Subproject
Most Jakarta subprojects allow you to customize Ant properties (with default
values defined in the "build.xml" file. This is done by creating a text file
named "ant.properties" in the source distribution directory (for property
definitions local to this subproject) and/or your user home directory (for
property definitions shared across subprojects). You can use the included
"ant.properties.sample" file as a starting point for this.
External dependencies are satisfied by configuring appropriate values in your
ant.properties file. The easiest way to satisfy these dependencies is to copy
the "ant.properties.sample" file (in the top-level directory) to "ant.properties",
and then edit it to suit your environment. On Unix, this would be done as:
cd @dist.name@
cp ant.properties.sample ant.properties
emacs ant.properties
NOTE: Be *sure* that you do not check "ant.properties" in to the CVS
repository. This file is local to your own development environment, and
each developer will have their own version.
(7) Build A Binary Distribution
Open a command line shell, and issue the following commands:
cd @dist.name@
ant -projecthelp
If everything is installed correctly, you should see a list of the Ant
"targets" that represent different commands you might wish to build. By
convention, the "jar" target creates the jar of the component. To execute
it, type the following commands:
cd @dist.name@
ant jar
This will create a jar in the @dist.name@/build/lib directory that contains
the component.
1.1 jakarta-avalon-excalibur/instrument/README.txt
Index: README.txt
===================================================================
Avalons Excalibur Instrument
----------------------------
WARNING: Under Development--the API may change
The instrument project provides an API for instrumenting
components.
Getting Started:
----------------
If you downloaded a source release of the component then you
will need to build the component. Directions for building the
component are located in BUILDING.txt
If you downloaded a binary release, or a release with both binary
and source then it is recomended you look over the documentation
in docs/index.html - and then look into the examples/ directory
for examples of the component in action.
1.1 jakarta-avalon-excalibur/instrument/ant.properties.sample
Index: ant.properties.sample
===================================================================
# -----------------------------------------------------------------------------
# Component ant.properties.sample
#
# This is an example "ant.properties" file, used to customize the building of
# the component for your local environment. It defines the location of all
# external modules that this component depend on. Copy this file to
# "ant.properties" in the source directory, and customize it as needed.
#
# The ant.properties values in this directory apply only to this component, and
# override the defaults in ../ant.properties.
#
# $Id: ant.properties.sample,v 1.1 2002/03/26 11:17:21 leif Exp $
# -----------------------------------------------------------------------------
# --------------------------------------------------
# COMPONENT-SPECIFIC REQUIRED LIBRARIES
# --------------------------------------------------
# ----- Compile Control Flags -----
build.debug=on
build.optimize=off
build.deprecation=off
# ----- Base Directory in which all the packages are stored -----
base.path=/opt
# --------------------------------------------------
# REQUIRED LIBRARIES
# --------------------------------------------------
# ----- JUnit Unit Test Suite, version 3.7 or later -----
junit.home=${base.path}/junit3.7
junit.lib=${junit.home}
junit.jar=${junit.lib}/junit.jar
# --------------------------------------------------
# OPTIONAL LIBRARIES
# --------------------------------------------------
# ----- Checkstyle, version 2.1 or later -----
# Uncomment the 'do.checkstyle' flag property to enable checkstyle
# do.checkstyle=
checkstyle.home=${base.path}/checkstyle-2.1
checkstyle.lib=${checkstyle.home}
checkstyle.jar=${checkstyle.lib}/checkstyle-all-2.1.jar
1.1 jakarta-avalon-excalibur/instrument/build.xml
Index: build.xml
===================================================================
<?xml version="1.0"?>
<project name="Excalibur Instrument" default="main" basedir=".">
<!-- load per-project properties -->
<property file="project.properties"/>
<!--
Give user a chance to override without editing this file
(and without typing -D each time he compiles it)
-->
<property file="ant.properties"/>
<property file="../ant.properties"/>
<property file="${user.home}/.ant.properties"/>
<!-- Settings used to configure compile environment -->
<property name="build.debug" value="on"/>
<property name="build.optimize" value="off"/>
<property name="build.deprecation" value="off"/>
<property name="build.compress" value="false"/>
<property name="junit.failonerror" value="false"/>
<!-- location of intermediate products -->
<property name="build.dir" value="build"/>
<property name="build.lib" value="${build.dir}/lib"/>
<property name="build.classes" value="${build.dir}/classes"/>
<property name="build.tests" value="${build.dir}/tests"/>
<property name="build.reports" value="${build.dir}/reports"/>
<!-- Set the properties for source directories -->
<property name="src.dir" value="src"/>
<property name="java.dir" value="${src.dir}/java"/>
<property name="test.dir" value="${src.dir}/test"/>
<!-- Set the properties for distribution directories -->
<property name="dist.dir" value="dist"/>
<property name="dist.javadocs" value="${dist.dir}/docs/api"/>
<!-- property to specify name of zip/jar files -->
<property name="dist.name" value="excalibur-${name}-${version}"/>
<!-- property indicating directory where all distribution archives are placed -->
<property name="dist.base" value="distributions"/>
<!-- Classpath for product -->
<path id="project.class.path">
<pathelement path="${java.class.path}"/>
<pathelement location="${build.classes}"/>
<pathelement location="${junit.jar}"/>
<pathelement location="${checkstyle.jar}"/>
</path>
<target name="main" depends="dist" description="Build the project"/>
<target name="rebuild" depends="clean,main" description="Rebuild the project"/>
<!-- Compiles the source code -->
<target name="compile" description="Compiles the source code">
<mkdir dir="${build.classes}"/>
<!-- Compile all classes including the tests. -->
<javac srcdir="${java.dir}"
destdir="${build.classes}"
debug="${build.debug}"
optimize="${build.optimize}"
deprecation="${build.deprecation}"
target="1.2">
<classpath refid="project.class.path" />
<src path="${test.dir}"/>
<include name="**/*.java"/>
</javac>
<!-- copy resources to same location as .class files -->
<copy todir="${build.classes}">
<fileset dir="${java.dir}">
<exclude name="**/*.java"/>
</fileset>
</copy>
<copy todir="${build.classes}">
<fileset dir="${test.dir}">
<exclude name="**/*.java"/>
</fileset>
</copy>
</target>
<!-- Creates all the .jar file -->
<target name="jar" depends="compile" description="Generates the jar files">
<mkdir dir="${build.lib}"/>
<jar jarfile="${build.lib}/${dist.name}.jar"
basedir="${build.classes}"
compress="${build.compress}">
<exclude name="**/test/**"/>
<zipfileset dir=".." prefix="META-INF/">
<include name="LICENSE.txt"/>
</zipfileset>
</jar>
</target>
<!-- Creates all the Javadocs -->
<target name="javadocs" depends="compile" description="Generates the javadocs">
<mkdir dir="${dist.javadocs}"/>
<javadoc packagenames="org.apache.*"
sourcepath="${java.dir}"
destdir="${dist.javadocs}">
<classpath refid="project.class.path" />
<doclet name="com.sun.tools.doclets.standard.Standard">
<param name="-author"/>
<param name="-version"/>
<param name="-doctitle" value="${Name}"/>
<param name="-windowtitle" value="${Name} API"/>
<param name="-link" value="http://java.sun.com/j2se/1.4/docs/api/"/>
<param name="-link" value="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
<param name="-link" value="http://jakarta.apache.org/avalon/api/"/>
<param name="-bottom"
value=""Copyright © ${year} Apache Jakarta Project. All Rights Reserved.""/>
</doclet>
</javadoc>
</target>
<target name="test" depends="compile" description="Perform the unit tests">
<echo message="Performing Unit Tests" />
<mkdir dir="${build.tests}"/>
<junit fork="true"
haltonfailure="${junit.failonerror}"
printsummary="yes"
dir="${build.tests}">
<classpath refid="project.class.path"/>
<formatter type="xml"/> <!-- xml reports for junitreport -->
<formatter type="plain"/> <!-- text reports for humans -->
<batchtest todir="${build.tests}">
<fileset dir="${build.classes}">
<include name="**/test/*TestCase.class"/>
<exclude name="**/Abstract*"/>
</fileset>
</batchtest>
</junit>
</target>
<target name="test-reports" depends="test" description="Generate Reports for the unit tests">
<mkdir dir="${build.reports}/junit"/>
<junitreport todir="${build.reports}/junit">
<fileset dir="${build.tests}">
<include name="TEST-*.xml"/>
</fileset>
<report format="frames" todir="${build.reports}/junit"/>
</junitreport>
<!-- Clean up the xml reports used by the junitreport task -->
<!--
<delete>
<fileset dir="${build.tests}" includes="TEST-*.xml"/>
<fileset dir="${build.tests}" includes="TESTS-*.xml"/>
</delete>
-->
</target>
<target name="jdepend" if="do.jdepend" description="Generate Dependency Analysis Report">
<!-- this invocation of jdepend requires the CVS version of ant for the xml format -->
<!-- thats why you are required to define do.jdepend property to generate the report -->
<jdepend outputfile="${build.dir}/jdepend-results.xml" format="xml" fork="yes">
<classpath refid="project.class.path"/>
<sourcespath>
<pathelement location="src/java" />
</sourcespath>
</jdepend>
<mkdir dir="${build.reports}/jdepend"/>
<style in="${build.dir}/jdepend-results.xml"
processor="trax"
out="${build.reports}/jdepend/delete-me.txt"
style="${ant.home}/etc/jdepend-frames.xsl"/>
</target>
<target name="checkstyle" if="do.checkstyle" description="Checkstyle">
<!-- this invocation of checkstyle requires that checkstyle be downloaded and setup -->
<!-- thats why you are required to define do.checkstyle property to generate the report -->
<taskdef name="checkstyle"
classname="com.puppycrawl.tools.checkstyle.CheckStyleTask">
<classpath refid="project.class.path"/>
</taskdef>
<checkstyle
lcurlyType="nl"
lcurlyMethod="nl"
lcurlyOther="nl"
rcurly="ignore"
allowProtected="false"
allowPackage="false"
allowNoAuthor="false"
maxLineLen="100"
maxMethodLen="100"
maxConstructorLen="100"
memberPattern="^m_[a-z][a-zA-Z0-9]*$"
staticPattern="^c_[a-z][a-zA-Z0-9]*$"
constPattern="(^c_[a-z][a-zA-Z0-9]*$)|([A-Z_]*$)"
ignoreImportLen="true"
allowTabs="false"
javadocScope="protected"
ignoreWhitespace="true"
cacheFile="checkstyle.cache"
failOnViolation="false"
ignoreCastWhitespace="true">
<fileset dir="${java.dir}">
<include name="**/*.java"/>
</fileset>
<formatter type="plain"/>
<formatter type="xml" toFile="build/checkstyle-results.xml"/>
</checkstyle>
</target>
<target name="checkstyle-report"
depends="checkstyle"
if="do.checkstyle"
description="Generate Checkstyle Report">
<mkdir dir="${build.reports}/checkstyle"/>
<style style="../tools/etc/checkstyle-frames.xsl" in="build/checkstyle-results.xml"
out="${build.reports}/checkstyle/delete-me.html"/>
</target>
<!-- Creates the distribution -->
<target name="dist"
depends="jar, test-reports, jdepend, checkstyle-report, javadocs"
description="Generates the jar files">
<mkdir dir="${dist.dir}"/>
<copy file="${build.lib}/${dist.name}.jar" todir="${dist.dir}"/>
<copy file="../LICENSE.txt" todir="${dist.dir}"/>
<copy file="../KEYS" todir="${dist.dir}"/>
<mkdir dir="${dist.base}"/>
<zip zipfile="${dist.base}/${dist.name}-bin.zip" compress="true">
<zipfileset dir="${dist.dir}" prefix="${dist.name}"/>
</zip>
<delete dir="${dist.dir}" />
</target>
<!-- Cleans up build and distribution directories -->
<target name="clean" description="Cleans up the project">
<delete file="checkstyle.cache"/>
<delete dir="${build.dir}" />
<delete dir="${dist.dir}" />
<delete dir="test" /> <!-- unit testing output directory -->
<delete>
<fileset dir="." includes="**/*~" defaultexcludes="no"/>
</delete>
</target>
<target name="real-clean" depends="clean" description="Cleans up the project, including distributions">
<delete dir="${dist.base}" />
</target>
</project>
1.1 jakarta-avalon-excalibur/instrument/project.properties
Index: project.properties
===================================================================
name=instrument
Name=Instrument
version=0.1
year=2002
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/AbstractInstrument.java
Index: AbstractInstrument.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.excalibur.instrument;
/**
* The AbstractInstrument class can be used by an class wishing to implement
* the Instruement interface.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public abstract class AbstractInstrument
implements Instrument
{
/** The name of the Instrument. */
private String m_name;
/** Proxy object used to communicate with the InstrumentManager. */
protected InstrumentProxy m_proxy;
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
/**
* Creates a new AbstractInstrument.
*
* @param name The name of the Instrument. The value should be a string
* which does not contain spaces or periods.
*/
protected AbstractInstrument( String name )
{
m_name = name;
}
/*---------------------------------------------------------------
* Instrument Methods
*-------------------------------------------------------------*/
/**
* Gets the name for the Instrument. When an Instrumentable publishes more
* than one Instrument, this name makes it possible to identify each
* Instrument. The value should be a string which does not contain
* spaces or periods.
*
* @return The name of the Instrument.
*/
public String getInstrumentName()
{
return m_name;
}
/*---------------------------------------------------------------
* Methods
*-------------------------------------------------------------*/
/**
* When the InstrumentManager is present, an InstrumentProxy will be set
* to enable the Instrument to communicate with the InstrumentManager.
* Once the InstrumentProxy is set, it should never be changed or set
* back to null. This restriction removes the need for synchronization
* within the Instrument classes. Which in turn makes them more
* efficient.
*
* @param proxy Proxy object used to communicate with the
* InstrumentManager.
*/
public void setInstrumentProxy( InstrumentProxy proxy )
{
if ( m_proxy != null )
{
throw new IllegalStateException(
"Once an InstrumentProxy has been set, it can not be changed." );
}
m_proxy = proxy;
}
/**
* Used by classes being profiled so that they can avoid unnecessary
* code when the data from an Instrument is not being used.
*
* @returns True if an InstrumentProxy has been set and is active.
*/
public boolean isActive()
{
return ( m_proxy != null ) && ( m_proxy.isActive() );
}
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/CounterInstrument.java
Index: CounterInstrument.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.excalibur.instrument;
/**
* CounterInstruments can be used to profile the number of times that
* something happens. They are perfect for profiling things like the number
* of times a class instance is created or destroyed. Or the number of
* times that a method is accessed.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public class CounterInstrument
extends AbstractInstrument
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
/**
* Creates a new CounterInstrument.
*
* @param name The name of the Instrument. The value should be a string
* which does not contain spaces or periods.
*/
public CounterInstrument( String name )
{
super( name );
}
/*---------------------------------------------------------------
* Methods
*-------------------------------------------------------------*/
/*
* Increments the Instrument. This method is optimized to be extremely
* light weight when an InstrumentManager is not present and there are no
* registered CounterInstrumentListeners.
*/
public void increment()
{
if ( m_proxy != null )
{
m_proxy.increment();
}
}
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/Instrument.java
Index: Instrument.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.excalibur.instrument;
/**
* The Instrument interface must by implemented by any object wishing to act
* as an instrument used by the instrument manager.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public interface Instrument
{
/**
* Gets the name for the Instrument. When an Instrumentable publishes more
* than one Instrument, this name makes it possible to identify each
* Instrument. The value should be a string which does not contain
* spaces or periods.
*
* @return The name of the Instrument.
*/
String getInstrumentName();
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/InstrumentManageable.java
Index: InstrumentManageable.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.excalibur.instrument;
/**
* Components which implement the InstrumentManageable Interface will have
* their InstrumentManager set by the component manager during their
* initialization phase. Components which create child components needs to
* implement this interface in order for Instruments to be supported within
* those child components.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.0
*/
public interface InstrumentManageable
{
/**
* Sets the InstrumentManager for child components. Can be for special
* purpose components, however it is used mostly internally.
*
* @param instrumentManager The InstrumentManager for the component to use.
*/
void setInstrumentManager( final InstrumentManager instrumentManager );
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/InstrumentManager.java
Index: InstrumentManager.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.excalibur.instrument;
import org.apache.avalon.excalibur.instrument.Instrumentable;
/**
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public interface InstrumentManager
{
/**
* Instrumentable to be registered with the instrument manager. Should be
* called whenever an Instrumentable is created.
*
* @param instrumentable Instrumentable to register with the InstrumentManager.
* @param instrumentableName The name to use when registering the Instrumentable.
*
* @throws Exception If there were any problems registering the Instrumentable.
*/
void registerInstrumentable( Instrumentable instrumentable, String instrumentableName )
throws Exception;
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/InstrumentProxy.java
Index: InstrumentProxy.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.excalibur.instrument;
/**
* Because some components using Instruments will be created in large numbers
* a way is needed to collect data from the instances of all instances of a
* component class without maintaining references to Instruments of each
* instance. An Instrument Manager can do this by making use of Instrument
* Proxies. Each Instrument is assigned a proxy when it is registered with
* the manager, then all communication is made through the proxy
* The Instrument interface must by implemented by any object wishing to act
* as an instrument used by the instrument manager.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public interface InstrumentProxy
{
/**
* Used by classes being profiles so that they can avoid unnecessary
* code when the data from a Instrument is not being used.
*
* @returns True if listeners are registered with the Instrument.
*/
boolean isActive();
/*
* Increments the Instrument. This method should be optimized to be extremely
* light weight when there are no registered CounterInstrumentListeners.
* <p>
* This method may throw an IllegalStateException if the proxy is not meant
* to handle calls to increment.
*/
void increment();
/**
* Sets the current value of the Instrument. This method is optimized
* to be extremely light weight when there are no registered
* ValueInstrumentListeners.
* <p>
* This method may throw an IllegalStateException if the proxy is not meant
* to handle calls to setValue.
*
* @param value The new value for the Instrument.
*/
void setValue( int value );
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/Instrumentable.java
Index: Instrumentable.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.excalibur.instrument;
/**
* The Instrumentable interface is to mark objects that can be sampled by an
* InstrumentManager. The getInstruments method may or may not be called
* depending on whether or not the ComponentManager used to create the
* Component supports Instrumentables. In most cases, an instrumentable
* object should always create its internal Instruments and make use of them
* as if instrument data were being collected. The Instruments are optimized
* so as not to reduce performance when they are not being used.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public interface Instrumentable
{
/**
* Empty Instrument array for use in hierarchical Instrumentable systems.
*/
Instrument[] EMPTY_INSTRUMENT_ARRAY = new Instrument[] {};
/**
* Empty Instrumentable array for use in hierarchical Instrumentable
* systems.
*/
Instrumentable[] EMPTY_INSTRUMENTABLE_ARRAY = new Instrumentable[] {};
/**
* 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.
*/
void setInstrumentableName( String name );
/**
* Gets the name of the Instrumentable.
*
* @return The name used to identify a Instrumentable.
*/
String getInstrumentableName();
/**
* 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.
*/
Instrument[] getInstruments();
/**
* 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.
*/
Instrumentable[] getChildInstrumentables();
}
1.1 jakarta-avalon-excalibur/instrument/src/java/org/apache/avalon/excalibur/instrument/ValueInstrument.java
Index: ValueInstrument.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.excalibur.instrument;
/**
* Objects implementing Instrumentable can create Instruments with integer
* values using a ValueInstrument. ValueInstruments are perfect for
* profiling things like system memory, or the size of a pool or cache.
*
* @author <a href="mailto:leif@silveregg.co.jp">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/26 11:17:21 $
* @since 4.1
*/
public class ValueInstrument
extends AbstractInstrument
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
/**
* Creates a new ValueInstrument.
*
* @param name The name of the Instrument. The value should be a string
* which does not contain spaces or periods.
*/
public ValueInstrument( String name )
{
super( name );
}
/*---------------------------------------------------------------
* Methods
*-------------------------------------------------------------*/
/**
* Sets the current value of the Instrument. This method is optimized
* to be extremely light weight when an InstrumentManager is not present
* and there are no registered ValueInstrumentListeners.
*
* @param value The new value for the Instrument.
*/
public void setValue( int value )
{
if ( m_proxy != null )
{
m_proxy.setValue( value );
}
}
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>