leif 2002/09/25 23:34:54
Modified: instrument/src/xdocs index.xml instrumentables.xml menu.xml
Added: instrument/src/test/org/apache/excalibur/instrument/test
AbstractInstrumentableImpl.java
AbstractLogEnabledInstrumentableImpl.java
CounterInstrumentTestCase.java
InstrumentableTestCase.java
LogEnabledInstrumentableTestCase.java
TestInstrumentProxy.java
ValueInstrumentTestCase.java
Log:
Add test cases for the Instrument project.
Revision Changes Path
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/AbstractInstrumentableImpl.java
Index: AbstractInstrumentableImpl.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.excalibur.instrument.test;
import org.apache.excalibur.instrument.AbstractInstrumentable;
import org.apache.excalibur.instrument.Instrument;
import org.apache.excalibur.instrument.Instrumentable;
/**
* Test Implementation of an AbstractInstrumentable.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class AbstractInstrumentableImpl
extends AbstractInstrumentable
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
public AbstractInstrumentableImpl( String name )
{
setInstrumentableName( name );
}
/*---------------------------------------------------------------
* AbstractInstrumentable Methods
*-------------------------------------------------------------*/
/**
* Adds an Instrument to the list of Instruments published by the
component.
* This method may not be called after the Instrumentable has been
* registered with the InstrumentManager.
*
* @param instrument Instrument to publish.
*/
public void addInstrument( Instrument instrument )
{
// Make this method public for testing.
super.addInstrument( instrument );
}
/**
* Adds a child Instrumentable to the list of child Instrumentables
* published by the component. This method may not be called after the
* Instrumentable has been registered with the InstrumentManager.
* <p>
* Note that Child Instrumentables must be named by the caller using the
* setInstrumentableName method.
*
* @param child Child Instrumentable to publish.
*/
public void addChildInstrumentable( Instrumentable child )
{
// Make this method public for testing.
super.addChildInstrumentable( child );
}
}
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/AbstractLogEnabledInstrumentableImpl.java
Index: AbstractLogEnabledInstrumentableImpl.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.excalibur.instrument.test;
import org.apache.excalibur.instrument.AbstractLogEnabledInstrumentable;
import org.apache.excalibur.instrument.Instrument;
import org.apache.excalibur.instrument.Instrumentable;
/**
* Test Implementation of an AbstractLogEnabledInstrumentable.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class AbstractLogEnabledInstrumentableImpl
extends AbstractLogEnabledInstrumentable
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
public AbstractLogEnabledInstrumentableImpl( String name )
{
setInstrumentableName( name );
}
/*---------------------------------------------------------------
* AbstractInstrumentable Methods
*-------------------------------------------------------------*/
/**
* Adds an Instrument to the list of Instruments published by the
component.
* This method may not be called after the Instrumentable has been
* registered with the InstrumentManager.
*
* @param instrument Instrument to publish.
*/
public void addInstrument( Instrument instrument )
{
// Make this method public for testing.
super.addInstrument( instrument );
}
/**
* Adds a child Instrumentable to the list of child Instrumentables
* published by the component. This method may not be called after the
* Instrumentable has been registered with the InstrumentManager.
* <p>
* Note that Child Instrumentables must be named by the caller using the
* setInstrumentableName method.
*
* @param child Child Instrumentable to publish.
*/
public void addChildInstrumentable( Instrumentable child )
{
// Make this method public for testing.
super.addChildInstrumentable( child );
}
}
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/CounterInstrumentTestCase.java
Index: CounterInstrumentTestCase.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.excalibur.instrument.test;
import junit.framework.TestCase;
import org.apache.excalibur.instrument.CounterInstrument;
/**
* Test of the CounterInstrument instrument.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class CounterInstrumentTestCase
extends TestCase
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
public CounterInstrumentTestCase( String name )
{
super( name );
}
/*---------------------------------------------------------------
* TestCase Methods
*-------------------------------------------------------------*/
/*---------------------------------------------------------------
* Test Cases
*-------------------------------------------------------------*/
public void testSimpleIncrementDisconnected() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
assertEquals( "A disconnected instrument should not be active.",
ci.isActive(), false );
ci.increment( 1 );
}
public void testCount1IncrementDisconnected() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
assertEquals( "A disconnected instrument should not be active.",
ci.isActive(), false );
ci.increment( 1 );
}
public void testCount0IncrementDisconnected() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
try
{
ci.increment( 0 );
fail( "calling increment with a count of 0 should fail." );
}
catch ( IllegalArgumentException e )
{
// Ok
}
}
public void testCountNegIncrementDisconnected() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
try
{
ci.increment( -1 );
fail( "calling increment with a negative count should fail." );
}
catch ( IllegalArgumentException e )
{
// Ok
}
}
public void testSimpleIncrementConnectedInactive() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
ci.setInstrumentProxy( proxy );
assertEquals( "The instrument should not be active.", ci.isActive(),
false );
ci.increment();
assertEquals( "The expected count was incorrect.", proxy.getValue(),
1 );
ci.increment();
assertEquals( "The expected count was incorrect.", proxy.getValue(),
2 );
}
public void testCount1IncrementConnectedInactive() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
ci.setInstrumentProxy( proxy );
assertEquals( "The instrument should not be active.", ci.isActive(),
false );
ci.increment( 1 );
assertEquals( "The expected count was incorrect.", proxy.getValue(),
1 );
ci.increment( 2 );
assertEquals( "The expected count was incorrect.", proxy.getValue(),
3 );
}
public void testSimpleIncrementConnectedActive() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
ci.setInstrumentProxy( proxy );
proxy.activate();
assertEquals( "The instrument should br active.", ci.isActive(), true
);
ci.increment();
assertEquals( "The expected count was incorrect.", proxy.getValue(),
1 );
}
public void testCount1IncrementConnectedActive() throws Exception
{
CounterInstrument ci = new CounterInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
ci.setInstrumentProxy( proxy );
proxy.activate();
assertEquals( "The instrument should br active.", ci.isActive(), true
);
ci.increment( 1 );
assertEquals( "The expected count was incorrect.", proxy.getValue(),
1 );
}
}
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/InstrumentableTestCase.java
Index: InstrumentableTestCase.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.excalibur.instrument.test;
import junit.framework.TestCase;
import org.apache.excalibur.instrument.CounterInstrument;
import org.apache.excalibur.instrument.Instrument;
import org.apache.excalibur.instrument.Instrumentable;
import org.apache.excalibur.instrument.ValueInstrument;
/**
* Test of the AbstractInstrumentable instrument.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class InstrumentableTestCase
extends TestCase
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
public InstrumentableTestCase( String name )
{
super( name );
}
/*---------------------------------------------------------------
* TestCase Methods
*-------------------------------------------------------------*/
/*---------------------------------------------------------------
* Methods
*-------------------------------------------------------------*/
private void generalTest( Instrument[] instruments, Instrumentable[]
children )
throws Exception
{
AbstractInstrumentableImpl impl = new AbstractInstrumentableImpl(
"base" );
// Set the name
impl.setInstrumentableName( "test" );
// Add the instruments
for ( int i = 0; i < instruments.length; i++ )
{
impl.addInstrument( instruments[i] );
}
// Add the child instrumentables
for ( int i = 0; i < children.length; i++ )
{
impl.addChildInstrumentable( children[i] );
}
// Verify the name
assertEquals( "Instrumentable name incorrect.",
impl.getInstrumentableName(), "test" );
// Verify the instruments
Instrument[] implInstruments = impl.getInstruments();
assertEquals( "The number of instruments is not correct.",
implInstruments.length, instruments.length );
for ( int i = 0; i < instruments.length; i++ )
{
assertEquals( "Instrument[i] is not correct.",
implInstruments[i], instruments[i] );
}
// Make sure that instruments can no longer be added
try
{
impl.addInstrument( new CounterInstrument( "bad" ) );
fail( "Should not have been able to add more instruments" );
}
catch ( IllegalStateException e )
{
// Ok
}
// Verify the child instrumentables
Instrumentable[] implChildren = impl.getChildInstrumentables();
assertEquals( "The number of child instrumentables is not correct.",
implChildren.length, children.length );
for ( int i = 0; i < children.length; i++ )
{
assertEquals( "Child[i] is not correct.", implChildren[i],
children[i] );
}
// Make sure that child instrumentables can no longer be added
try
{
impl.addChildInstrumentable( new AbstractInstrumentableImpl(
"bad" ) );
fail( "Should not have been able to add more child
instrumentables" );
}
catch ( IllegalStateException e )
{
// Ok
}
}
/*---------------------------------------------------------------
* Test Cases
*-------------------------------------------------------------*/
public void testEmpty() throws Exception
{
Instrument[] instruments = new Instrument[] {};
Instrumentable[] children = new Instrumentable[] {};
generalTest( instruments, children );
}
public void test1Instrument() throws Exception
{
Instrument[] instruments = new Instrument[]
{
new CounterInstrument( "c1" )
};
Instrumentable[] children = new Instrumentable[] {};
generalTest( instruments, children );
}
public void testNInstrument() throws Exception
{
Instrument[] instruments = new Instrument[]
{
new CounterInstrument( "c1" ),
new ValueInstrument( "v1" ),
new CounterInstrument( "c2" ),
new ValueInstrument( "v2" ),
new CounterInstrument( "c3" ),
new ValueInstrument( "v3" ),
new CounterInstrument( "c4" ),
new ValueInstrument( "v4" )
};
Instrumentable[] children = new Instrumentable[] {};
generalTest( instruments, children );
}
public void test1ChildInstrumentable() throws Exception
{
Instrument[] instruments = new Instrument[] {};
Instrumentable[] children = new Instrumentable[]
{
new AbstractInstrumentableImpl( "i1" )
};
generalTest( instruments, children );
}
public void testNChildInstrumentable() throws Exception
{
Instrument[] instruments = new Instrument[] {};
Instrumentable[] children = new Instrumentable[]
{
new AbstractInstrumentableImpl( "i1" ),
new AbstractInstrumentableImpl( "i2" ),
new AbstractInstrumentableImpl( "i3" ),
new AbstractInstrumentableImpl( "i4" ),
new AbstractInstrumentableImpl( "i5" ),
new AbstractInstrumentableImpl( "i6" )
};
generalTest( instruments, children );
}
}
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/LogEnabledInstrumentableTestCase.java
Index: LogEnabledInstrumentableTestCase.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.excalibur.instrument.test;
import junit.framework.TestCase;
import org.apache.avalon.framework.logger.ConsoleLogger;
import org.apache.excalibur.instrument.CounterInstrument;
import org.apache.excalibur.instrument.Instrument;
import org.apache.excalibur.instrument.Instrumentable;
import org.apache.excalibur.instrument.ValueInstrument;
/**
* Test of the AbstractLogEnabledInstrumentable instrument.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class LogEnabledInstrumentableTestCase
extends TestCase
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
public LogEnabledInstrumentableTestCase( String name )
{
super( name );
}
/*---------------------------------------------------------------
* TestCase Methods
*-------------------------------------------------------------*/
/*---------------------------------------------------------------
* Methods
*-------------------------------------------------------------*/
private void generalTest( Instrument[] instruments, Instrumentable[]
children )
throws Exception
{
AbstractLogEnabledInstrumentableImpl impl =
new AbstractLogEnabledInstrumentableImpl( "base" );
impl.enableLogging( new ConsoleLogger() );
// Set the name
impl.setInstrumentableName( "test" );
// Add the instruments
for ( int i = 0; i < instruments.length; i++ )
{
impl.addInstrument( instruments[i] );
}
// Add the child instrumentables
for ( int i = 0; i < children.length; i++ )
{
impl.addChildInstrumentable( children[i] );
}
// Verify the name
assertEquals( "Instrumentable name incorrect.",
impl.getInstrumentableName(), "test" );
// Verify the instruments
Instrument[] implInstruments = impl.getInstruments();
assertEquals( "The number of instruments is not correct.",
implInstruments.length, instruments.length );
for ( int i = 0; i < instruments.length; i++ )
{
assertEquals( "Instrument[i] is not correct.",
implInstruments[i], instruments[i] );
}
// Make sure that instruments can no longer be added
try
{
impl.addInstrument( new CounterInstrument( "bad" ) );
fail( "Should not have been able to add more instruments" );
}
catch ( IllegalStateException e )
{
// Ok
}
// Verify the child instrumentables
Instrumentable[] implChildren = impl.getChildInstrumentables();
assertEquals( "The number of child instrumentables is not correct.",
implChildren.length, children.length );
for ( int i = 0; i < children.length; i++ )
{
assertEquals( "Child[i] is not correct.", implChildren[i],
children[i] );
}
// Make sure that child instrumentables can no longer be added
try
{
impl.addChildInstrumentable( new AbstractInstrumentableImpl(
"bad" ) );
fail( "Should not have been able to add more child
instrumentables" );
}
catch ( IllegalStateException e )
{
// Ok
}
}
/*---------------------------------------------------------------
* Test Cases
*-------------------------------------------------------------*/
public void testEmpty() throws Exception
{
Instrument[] instruments = new Instrument[] {};
Instrumentable[] children = new Instrumentable[] {};
generalTest( instruments, children );
}
public void test1Instrument() throws Exception
{
Instrument[] instruments = new Instrument[]
{
new CounterInstrument( "c1" )
};
Instrumentable[] children = new Instrumentable[] {};
generalTest( instruments, children );
}
public void testNInstrument() throws Exception
{
Instrument[] instruments = new Instrument[]
{
new CounterInstrument( "c1" ),
new ValueInstrument( "v1" ),
new CounterInstrument( "c2" ),
new ValueInstrument( "v2" ),
new CounterInstrument( "c3" ),
new ValueInstrument( "v3" ),
new CounterInstrument( "c4" ),
new ValueInstrument( "v4" )
};
Instrumentable[] children = new Instrumentable[] {};
generalTest( instruments, children );
}
public void test1ChildInstrumentable() throws Exception
{
Instrument[] instruments = new Instrument[] {};
Instrumentable[] children = new Instrumentable[]
{
new AbstractInstrumentableImpl( "i1" )
};
generalTest( instruments, children );
}
public void testNChildInstrumentable() throws Exception
{
Instrument[] instruments = new Instrument[] {};
Instrumentable[] children = new Instrumentable[]
{
new AbstractInstrumentableImpl( "i1" ),
new AbstractInstrumentableImpl( "i2" ),
new AbstractInstrumentableImpl( "i3" ),
new AbstractInstrumentableImpl( "i4" ),
new AbstractInstrumentableImpl( "i5" ),
new AbstractInstrumentableImpl( "i6" )
};
generalTest( instruments, children );
}
}
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/TestInstrumentProxy.java
Index: TestInstrumentProxy.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.excalibur.instrument.test;
import org.apache.excalibur.instrument.InstrumentProxy;
/**
* Dummy InstrumentProxy used to test instruments.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class TestInstrumentProxy
implements InstrumentProxy
{
private boolean m_active;
private int m_value;
/*---------------------------------------------------------------
* InstrumentProxy Methods
*-------------------------------------------------------------*/
/**
* Used by classes being profiles so that they can avoid unnecessary
* code when the data from a Instrument is not being used.
*
* @return True if listeners are registered with the Instrument.
*/
public boolean isActive()
{
return m_active;
}
/**
* Increments the Instrument by a specified count. 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.
*
* @param count A positive integer to increment the counter by.
*/
public void increment( int count )
{
m_value += count;
}
/**
* 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.
*/
public void setValue( int value )
{
m_value = value;
}
/*---------------------------------------------------------------
* Methods
*-------------------------------------------------------------*/
/**
* Sets the activate flag on the proxy so that it will collect
information.
*/
public void activate()
{
m_active = true;
}
/**
**/
public int getValue()
{
return m_value;
}
}
1.1
jakarta-avalon-excalibur/instrument/src/test/org/apache/excalibur/instrument/test/ValueInstrumentTestCase.java
Index: ValueInstrumentTestCase.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.excalibur.instrument.test;
import junit.framework.TestCase;
import org.apache.excalibur.instrument.ValueInstrument;
/**
* Test of the ValueInstrument instrument.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leif Mortenson</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/09/26 06:34:53 $
*/
public class ValueInstrumentTestCase
extends TestCase
{
/*---------------------------------------------------------------
* Constructors
*-------------------------------------------------------------*/
public ValueInstrumentTestCase( String name )
{
super( name );
}
/*---------------------------------------------------------------
* TestCase Methods
*-------------------------------------------------------------*/
/*---------------------------------------------------------------
* Test Cases
*-------------------------------------------------------------*/
public void testSimpleValueDisconnected() throws Exception
{
ValueInstrument vi = new ValueInstrument( "testInstrument" );
assertEquals( "A disconnected instrument should not be active.",
vi.isActive(), false );
vi.setValue( 0 );
vi.setValue( -1 );
vi.setValue( 1 );
}
public void testSimpleValueConnectedInactive() throws Exception
{
ValueInstrument vi = new ValueInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
vi.setInstrumentProxy( proxy );
assertEquals( "The instrument should not be active.", vi.isActive(),
false );
vi.setValue( 0 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
0 );
vi.setValue( -1 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
-1 );
vi.setValue( 1 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
1 );
}
public void testLargeValueConnectedInactive() throws Exception
{
ValueInstrument vi = new ValueInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
vi.setInstrumentProxy( proxy );
assertEquals( "The instrument should not be active.", vi.isActive(),
false );
vi.setValue( 1313123123 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
1313123123 );
vi.setValue( -325353253 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
-325353253 );
}
public void testSimpleValueConnectedActive() throws Exception
{
ValueInstrument vi = new ValueInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
vi.setInstrumentProxy( proxy );
proxy.activate();
assertEquals( "The instrument should br active.", vi.isActive(), true
);
vi.setValue( 0 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
0 );
vi.setValue( -1 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
-1 );
vi.setValue( 1 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
1 );
}
public void testLargeValueConnectedActive() throws Exception
{
ValueInstrument vi = new ValueInstrument( "testInstrument" );
TestInstrumentProxy proxy = new TestInstrumentProxy();
vi.setInstrumentProxy( proxy );
proxy.activate();
assertEquals( "The instrument should br active.", vi.isActive(), true
);
vi.setValue( 1313123123 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
1313123123 );
vi.setValue( -325353253 );
assertEquals( "The expected value was incorrect.", proxy.getValue(),
-325353253 );
}
}
1.3 +1 -0 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 29 Jul 2002 18:45:09 -0000 1.2
+++ index.xml 26 Sep 2002 06:34:54 -0000 1.3
@@ -5,6 +5,7 @@
<title>Excalibur Instrument - Overview</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ <person name="Leif Mortenson" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
1.2 +91 -49
jakarta-avalon-excalibur/instrument/src/xdocs/instrumentables.xml
Index: instrumentables.xml
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/instrument/src/xdocs/instrumentables.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- instrumentables.xml 29 Jul 2002 18:45:09 -0000 1.1
+++ instrumentables.xml 26 Sep 2002 06:34:54 -0000 1.2
@@ -1,49 +1,91 @@
<?xml version="1.0"?>
<document>
- <header>
- <title>Excalibur Instrument - Enable Instrumenting</title>
- <authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
- </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>
+ <header>
+ <title>Excalibur Instrument - Enable Instrumenting</title>
+ <authors>
+ <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ </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>
+ <p>
+ Instrumentation has been designed from the start with
performance in mind
+ you can feel comfortable instrumenting your code without
worrying about
+ how it will effect performance. When your code is running
in an environment
+ where it has not been registered with an
InstrumentationManager, the Instrument
+ code acts as a noop. In cases where the your code is
registered with an
+ InstrumentationManager, the Instrument is still a noop
unless the instrument
+ output is actually been monitored. This makes it possible
to place
+ Instrumentation throughout your code just as would be done
with debug logging
+ information. When the Instrument data is required, it can
be requested at any
+ time. Even from a live running system.
+ </p>
+ </s1>
+ <s1 title="Getting Started">
+ <p>
+ The first thing that you will need to do to Instrument
enable your class
+ is to modify your class to implement the
<code>Instrumentable</code> interface.
+ There are currently three ways of acomplishing this, each of
which are described
+ in detail below. 1) Extend
<code>AbstractInstrumentable</code>, 2) Extend
+ <code>AbstractLogEnabledInstrumentable</code> and 3)
Implement
+ <code>Instrumentable</code>.
+ </p>
+ <s2 title="Extending AbstractInstrumentable">
+ <p>
+ The first option works well in cases where your code
does not already have a
+ super class. You simply extend the
<code>AbstractInstrumentable</code> class
+ create and register your Instruments in your class's
constructor and then
+ use the Instruments at the appropriate locations in your
code. All of the
+ details of telling your class how to register itself
with an
+ <code>InstrumentManager</code> are taken care of for you.
+ </p>
+ <source>
+<![CDATA[
+]]>
+ </source>
+ </s2>
+
+ <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>
+ </source>
+ <p>
+ Once you do that, you need to implement the
<code>Instrumentable</code>
+ interface or extend one of the available utility classes:
+ <code>AbstractInstrumentable</code> or
+ <code>AbstractLogEnabledInstrumentable</code>.
+ </p>
+
+ <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
@@ -135,15 +177,15 @@
}
}
]]>
- </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>
+ </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
@@ -157,7 +199,7 @@
return m_dictionary.get( name );
}
]]>
- </source>
- </s1>
- </body>
+ </source>
+ </s1>
+ </body>
</document>
1.3 +5 -5 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- menu.xml 29 Jul 2002 18:45:09 -0000 1.2
+++ menu.xml 26 Sep 2002 06:34:54 -0000 1.3
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
-<project
- href="http://jakarta.apache.org/avalon/excalibur/instrument/";
- name="Excalibur Instrument">
-
+<project href="http://jakarta.apache.org/avalon/excalibur/instrument/";
name="Excalibur Instrument">
<title>Excalibur Instrument</title>
<body>
<menu name="Related">
- <item href="../fortress/" name="Excalibur Fortress"/>
+ <menu name="Containers">
+ <item href="../component/" name="Excalibur Component
Manager"/>
+ <item href="../fortress/" name="Excalibur Fortress"/>
+ </menu>
</menu>
<menu name="About">
<item name="Overview" href="index.html"/>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
