You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by bl...@apache.org on 2002/07/29 20:45:09 UTC
cvs commit: jakarta-avalon-excalibur/instrument/src/xdocs instrumentables.xml index.xml menu.xml
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>