donaldp 02/03/31 05:27:57
Added: src/proposal/avalon5 build.xml
src/proposal/avalon5/org/apache/framework/activity
Initializable.java Startable.java Suspendable.java
package.html
src/proposal/avalon5/org/apache/framework/configuration
AbstractConfiguration.java Configurable.java
Configuration.java ConfigurationException.java
package.html
src/proposal/avalon5/org/apache/framework/configuration/impl
DefaultConfiguration.java
DefaultConfigurationBuilder.java
DefaultConfigurationSerializer.java
NamespacedSAXConfigurationHandler.java
SAXConfigurationHandler.java
src/proposal/avalon5/org/apache/framework/context
Context.java ContextException.java
Contextualizable.java package.html
src/proposal/avalon5/org/apache/framework/context/impl
DefaultContext.java
src/proposal/avalon5/org/apache/framework/logger
AbstractLogEnabled.java LogEnabled.java Logger.java
package.html
src/proposal/avalon5/org/apache/framework/logger/impl
ConsoleLogger.java Jdk14Logger.java
Log4JLogger.java LogKitLogger.java NullLogger.java
src/proposal/avalon5/org/apache/framework/parameters
ParameterException.java Parameterizable.java
Parameters.java package.html
src/proposal/avalon5/org/apache/framework/service
ServiceException.java ServiceManager.java
Serviceable.java package.html
src/proposal/avalon5/org/apache/framework/service/impl
DefaultServiceManager.java
Log:
Start playinmg with ideas for framework5
Revision Changes Path
1.1 jakarta-avalon/src/proposal/avalon5/build.xml
Index: build.xml
===================================================================
<?xml version="1.0"?>
<project name="Avalon Framework5" default="main" basedir=".">
<target name="main" description="compiles the source code">
<mkdir dir="../../../build/classes"/>
<javac srcdir="." destdir="../../../build/classes">
<classpath>
<pathelement location="../../../tools/ext/logkit.jar"/>
<pathelement location="../../../tools/lib/xerces-1.4.4.jar"/>
<pathelement location="../../../tools/lib/*.jar"/>
<pathelement path="${java.class.path}" />
</classpath>
<exclude
name="org/apache/framework/logger/impl/Log4JLogger.java"/>
<exclude
name="org/apache/framework/logger/impl/Jdk14Logger.java"/>
<exclude
name="org/apache/framework/configuration/impl/DefaultConfigurationSerializer.java"/>
</javac>
</target>
</project>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/Initializable.java
Index: Initializable.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.framework.activity;
/**
* The Initializable interface is used by components that need to
* allocate resources prior to them becoming active and/or
* deallocate and dispose resources prior to their destruction.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public interface Initializable
{
/**
* Initialialize the component. Initialization includes
* allocating any resources required throughout the
* components lifecycle.
*
* @exception Exception if an error occurs
*/
void initialize()
throws Exception;
/**
* The dispose operation is called at the end of a components lifecycle.
* This method will be called after Startable.stop() method (if
implemented
* by component). Components use this method to release and destroy any
* resources that the Component owns.
*/
void dispose();
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/Startable.java
Index: Startable.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.framework.activity;
/**
* The Startable interface is used when components need to
* be "running" to be active. It provides a method through
* which components can be "started" and "stopped" without
* requiring a thread.
* Note that these methods should start the component but return
* imediately.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface Startable
{
/**
* Starts the component.
*
* @exception Exception if Component can not be started
*/
void start()
throws Exception;
/**
* Stops the component.
*
* @exception Exception if the Component can not be Stopped.
*/
void stop()
throws Exception;
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/Suspendable.java
Index: Suspendable.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.framework.activity;
/**
* The Suspendable interface is used when a component
* will need to temporarily halt execution of a component.
* The execution may be halted so that you can reconfigure/
* recompose/recontextualize component.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface Suspendable
{
/**
* Suspends the component.
*/
void suspend();
/**
* Resumes the component.
*/
void resume();
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/activity/package.html
Index: package.html
===================================================================
<body>
Activity related interfaces covering component initialization, execution,
startable and stoppable components, suspension, and disposal.
</body>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/AbstractConfiguration.java
Index: AbstractConfiguration.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.framework.configuration;
import org.apache.framework.configuration.impl.DefaultConfiguration;
/**
* This is an abstract <code>Configuration</code> implementation that deals
* with methods that can be abstracted away from underlying implementations.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @version CVS $Revision: 1.1 $ $Date: 2002/03/31 13:27:56 $
*/
public abstract class AbstractConfiguration
implements Configuration
{
/**
* Returns the prefix of the namespace. This is only used as a
serialization
* hint, therefore is not part of the client API. It should be included
in
* all Configuration implementations though.
* @return A non-null String (defaults to "")
* @throws ConfigurationException if no prefix was defined (prefix is
* <code>null</code>.
*/
protected abstract String getPrefix() throws ConfigurationException;
/**
* Returns the value of the configuration element as an <code>int</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @exception ConfigurationException if an error occurs
* @return the value
*/
public int getValueAsInteger()
throws ConfigurationException
{
final String value = getValue();
try
{
if( value.startsWith( "0x" ) )
{
return Integer.parseInt( value.substring( 2 ), 16 );
}
else if( value.startsWith( "0o" ) )
{
return Integer.parseInt( value.substring( 2 ), 8 );
}
else if( value.startsWith( "0b" ) )
{
return Integer.parseInt( value.substring( 2 ), 2 );
}
else
{
return Integer.parseInt( value );
}
}
catch( final Exception nfe )
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as an integer in the
configuration element \"" +
getName() + "\" at " +
getLocation() );
}
}
/**
* Returns the value of the configuration element as an <code>int</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public int getValueAsInteger( final int defaultValue )
{
try
{
return getValueAsInteger();
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the configuration element as a <code>long</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @exception ConfigurationException if an error occurs
* @return the value
*/
public long getValueAsLong()
throws ConfigurationException
{
final String value = getValue();
try
{
if( value.startsWith( "0x" ) )
{
return Long.parseLong( value.substring( 2 ), 16 );
}
else if( value.startsWith( "0o" ) )
{
return Long.parseLong( value.substring( 2 ), 8 );
}
else if( value.startsWith( "0b" ) )
{
return Long.parseLong( value.substring( 2 ), 2 );
}
else
{
return Integer.parseInt(value);
}
}
catch( final Exception nfe )
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as a long in the
configuration element \"" +
getName() + "\" at " +
getLocation() );
}
}
/**
* Returns the value of the configuration element as a <code>long</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public long getValueAsLong( final long defaultValue )
{
try
{
return getValueAsLong();
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the configuration element as a <code>float</code>.
*
* @exception ConfigurationException if an error occurs
* @return the value
*/
public float getValueAsFloat()
throws ConfigurationException
{
final String value = getValue();
try
{
return Float.parseFloat( value );
}
catch( final Exception nfe )
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as a float in the
configuration element \"" +
getName() + "\" at " +
getLocation() );
}
}
/**
* Returns the value of the configuration element as a <code>float</code>.
*
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public float getValueAsFloat( final float defaultValue )
{
try
{
return getValueAsFloat();
}
catch( final ConfigurationException ce )
{
return(defaultValue);
}
}
/**
* Returns the value of the configuration element as a
<code>boolean</code>.
*
* @exception ConfigurationException if an error occurs
* @return the value
*/
public boolean getValueAsBoolean()
throws ConfigurationException
{
final String value = getValue();
if( value.equals( "true" ) )
{
return true;
}
else if( value.equals( "false" ) )
{
return false;
}
else
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as a boolean in the
configuration element \"" +
getName() + "\" at " +
getLocation() );
}
}
/**
* Returns the value of the configuration element as a
<code>boolean</code>.
*
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public boolean getValueAsBoolean( final boolean defaultValue )
{
try
{
return getValueAsBoolean();
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the configuration element as a
<code>String</code>.
*
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public String getValue( final String defaultValue )
{
try
{
return getValue();
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the attribute specified by its name as an
* <code>int</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of the attribute
* @exception ConfigurationException if an error occurs
* @return the value
*/
public int getAttributeAsInteger( final String name )
throws ConfigurationException
{
final String value = getAttribute( name );
try
{
if( value.startsWith( "0x" ) )
{
return Integer.parseInt( value.substring( 2 ), 16 );
}
else if( value.startsWith( "0o" ) )
{
return Integer.parseInt( value.substring( 2 ), 8);
}
else if( value.startsWith( "0b" ) )
{
return Integer.parseInt( value.substring( 2 ), 2 );
}
else
{
return Integer.parseInt(value);
}
}
catch( final Exception nfe )
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as an integer in the
attribute \"" +
name + "\" at " + getLocation()
);
}
}
/**
* Returns the value of the attribute specified by its name as an
* <code>int</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of the attribute
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public int getAttributeAsInteger( final String name, final int
defaultValue )
{
try
{
return getAttributeAsInteger( name );
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>long</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of the attribute
* @exception ConfigurationException if an error occurs
* @return the value
*/
public long getAttributeAsLong( final String name )
throws ConfigurationException
{
final String value = getAttribute( name );
try
{
if( value.startsWith( "0x" ) )
{
return Long.parseLong( value.substring( 2 ), 16 );
}
else if( value.startsWith( "0o" ) )
{
return Long.parseLong( value.substring( 2 ), 8 );
}
else if( value.startsWith( "0b" ) )
{
return Long.parseLong( value.substring( 2 ), 2);
}
else
{
return Long.parseLong( value );
}
}
catch( final Exception nfe )
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as a long in the attribute
\"" +
name + "\" at " + getLocation()
);
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>long</code>.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of the attribute
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public long getAttributeAsLong( final String name, final long
defaultValue )
{
try
{
return getAttributeAsLong( name );
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>float</code>.
*
* @param name the name of the attribute
* @exception ConfigurationException if an error occurs
* @return the value
*/
public float getAttributeAsFloat( final String name )
throws ConfigurationException
{
final String value = getAttribute( name );
try
{
return Float.parseFloat( value );
}
catch( final Exception e )
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as a float in the attribute
\"" +
name + "\" at " + getLocation()
);
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>float</code>.
*
* @param name the name of the attribute
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public float getAttributeAsFloat( final String name, final float
defaultValue )
{
try
{
return getAttributeAsFloat( name );
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>boolean</code>.
*
* @param name the name of the attribute
* @exception ConfigurationException if an error occurs
* @return the value
*/
public boolean getAttributeAsBoolean( final String name )
throws ConfigurationException
{
final String value = getAttribute( name );
if( value.equalsIgnoreCase( "true" ) )
{
return true;
}
else if( value.equalsIgnoreCase( "false" ) )
{
return false;
}
else
{
throw new ConfigurationException( "Cannot parse the value \"" +
value +
"\" as a boolean in the
attribute \"" +
name + "\" at " + getLocation()
);
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>boolean</code>.
*
* @param name the name of the attribute
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public boolean getAttributeAsBoolean( final String name, final boolean
defaultValue )
{
try
{
return getAttributeAsBoolean( name );
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>String</code>.
*
* @param name the name of the attribute
* @param defaultValue the default value to return if value malformed or
empty
* @return the value
*/
public String getAttribute( final String name, final String defaultValue )
{
try
{
return getAttribute( name );
}
catch( final ConfigurationException ce )
{
return defaultValue;
}
}
/**
* Return the first <code>Configuration</code> object child of this
* associated with the given name. If no such child exists, a new one
* will be created.
*
* @param name the name of the child
* @return the child Configuration
*/
public Configuration getChild( final String name )
{
return getChild( name, true );
}
/**
* Return the first <code>Configuration</code> object child of this
* associated with the given name.
*
* @param name the name of the child
* @param createNew true if you want to create a new Configuration object
if none exists
* @return the child Configuration
*/
public Configuration getChild( final String name, final boolean createNew
)
{
final Configuration[] children = getChildren( name );
if( children.length > 0 )
{
return children[ 0 ];
}
else
{
if( createNew )
{
return new DefaultConfiguration( name, "-" );
}
else
{
return null;
}
}
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/Configurable.java
Index: Configurable.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.framework.configuration;
/**
* This interface should be implemented by classes that need to be
* configured with custom parameters before initialization.
* <br />
*
* The contract surrounding a <code>Configurable</code> is that the
* instantiating entity must call the <code>configure</code>
* method before it is valid. The <code>configure</code> method
* must be called after the constructor, and before any other method.
* <br/>
*
* Note that this interface is incompatible with Parameterizable.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @version 1.0
*/
public interface Configurable
{
/**
* Pass the <code>Configuration</code> to the <code>Configurable</code>
* class. This method must always be called after the constructor
* and before any other method.
*
* @param configuration the class configurations.
* @exception ConfigurationException if an error occurs
*/
void configure( Configuration configuration )
throws ConfigurationException;
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/Configuration.java
Index: Configuration.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.framework.configuration;
/**
* <code>Configuration</code> is a interface encapsulating a configuration
node
* used to retrieve configuration values.
*
* <p>
* This is a "read only" interface preventing applications from modifying
their
* own configurations. Once it is created, the information never changes.
* </p>
* <h3>Data Model</h3>
* <p>
* The data model is a subset of XML's; a single-rooted hierarchical tree
where each
* node can contain multiple <em>attributes</em>, and leaf nodes can also
* contain a <em>value</em>. Reflecting this, <code>Configuration</code>s are
* usually built from an XML file by the [EMAIL PROTECTED]
org.apache.framework.configuration.impl.DefaultConfigurationBuilder}
* class, or directly by a SAX parser using a [EMAIL PROTECTED]
org.apache.framework.configuration.impl.SAXConfigurationHandler} or
* [EMAIL PROTECTED]
org.apache.framework.configuration.impl.NamespacedSAXConfigurationHandler}
event handler.
* </p>
* <h4>Namespace support</h4>
* <p>
* Since version 4.1, each <code>Configuration</code> node has a namespace
* associated with it, in the form of a string, accessible through [EMAIL
PROTECTED]
* #getNamespace}. If no namespace is present, <code>getNamespace</code> will
* return blank (""). See [EMAIL PROTECTED]
org.apache.framework.configuration.impl.DefaultConfigurationBuilder} for
details on how
* XML namespaces are mapped to <code>Configuration</code> namespaces.
* </p>
* <h3>Example</h3>
* <p>
* As an example, consider two <code>Configuration</code>s (with and without
* namespaces) built from this XML:
* </p>
* <pre>
* <my-system version="1.3" xmlns:doc="http://myco.com/documentation">
* <doc:desc>This is a highly fictitious config file</doc:desc>
* <widget name="fooWidget" initOrder="1" threadsafe="true"/>
* </my-system>
* </pre>
* <p>If namespace support is enabled (eg through [EMAIL PROTECTED]
* DefaultConfigurationBuilder#DefaultConfigurationBuilder(boolean) new
* DefaultConfigurationBuilder(true)}), then the <code>xmlns:doc</code>
element
* will not translate into a Configuration attribute, and the
* <code>doc:desc</code> element will become a <code>Configuration</code> node
* with name "desc" and namespace "http://myco.com/documentation";. The
* <code>widget</code> element will have namespace "".
* </p>
* <p>If namespace support is disabled (the default for [EMAIL PROTECTED]
* DefaultConfigurationBuilder}), the above XML will translate directly to
* <code>Configuration</code> nodes. The <code>my-system</code> node will have
* an attribute named "xmlns:doc", and a child called "doc:desc".
* </p>
* <p>
* Assuming the <code>Configuration</code> object is named <code>conf</code>,
* here is how the data could be retrieved:
* </p>
* <table border="1">
* <tr align="center"><th>Code</th><th>No namespaces</th><th>With
namespaces</th></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getName getName}()</code></td><td
colspan="2">my-system</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getAttributeNames
getAttributeNames}().length</code>
* </td><td>2</td><td>1</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChildren getChildren}().length</code>
* </td><td colspan="2">2</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getAttributeAsFloat
getAttributeAsFloat}("version")</code>
* </td><td colspan="2">1.3</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL PROTECTED]
#getAttribute getAttribute}("name")</code>
* </td><td colspan="2">fooWidget</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("widget")
* [EMAIL PROTECTED] #getAttributeAsBoolean
getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2">
* <code>true</code></td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("widget")[EMAIL PROTECTED]
#getLocation getLocation}()</code>
* </td><td
colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL PROTECTED]
#getName getName}()</code>
* </td><td>desc (see [EMAIL PROTECTED]
#getChild(String)})</td><td>desc</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("doc:desc")[EMAIL PROTECTED]
#getName getName}()</code>
* </td><td>doc:desc</td><td>doc:desc (see [EMAIL PROTECTED]
#getChild(String)})</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL PROTECTED]
#getValue getValue}()</code>
* </td><td>[EMAIL PROTECTED] ConfigurationException}</td><td>This is a
highly fictitious config file</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("doc:desc")[EMAIL PROTECTED]
#getValue getValue}()</code>
* </td><td>This is a highly fictitious config file</td><td>[EMAIL PROTECTED]
ConfigurationException}</td></tr>
* <tr align="center"><td align="left">
* <code>[EMAIL PROTECTED] #getChild getChild}("desc")[EMAIL PROTECTED]
#getNamespace getNamespace}()</code>
* </td><td> </td><td>http://myco.com/documentation";</td></tr>
* </table>
* </p>
* <p>
* Type-safe utility methods are provided for retrieving attribute and element
* values as <code>String</code>, <code>int</code>, <code>long</code>,
* <code>float</code> and <code>boolean</code>.
* </p>
* <h3>Miscellanea</h3>
* <p>
* Currently, the configuration tree can only be traversed one node at a time,
* eg., through [EMAIL PROTECTED] #getChild getChild("foo")} or [EMAIL
PROTECTED] #getChildren}. In
* a future release, it may be possible to access child nodes with an
XPath-like
* syntax.
* </p>
* <p>
* Checking for the existence of an attribute can be done as follows:
* </p>
* <pre>
*String value = conf.getAttribute( "myAttribute", null );
* if ( null == value )
* {
* // Do the processing applicable if the attribute isn't present.
* }
* </pre>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Jeff Turner</a>
* @version 1.0
*/
public interface Configuration
{
/**
* Return the name of the node.
*
* @return name of the <code>Configuration</code> node.
* @post getName() != null
*
*/
String getName();
/**
* Return a string describing location of Configuration.
* Location can be different for different mediums (ie "file:line" for
normal XML files or
* "table:primary-key" for DB based configurations);
*
* @return a string describing location of Configuration
*/
String getLocation();
/**
* Returns a string indicating which namespace this Configuration node
* belongs to.
*
* <p>
* What this returns is dependent on the configuration file and the
* Configuration builder. If the Configuration builder does not support
* namespaces, this method will return a blank string.
* </p>
* <p>In the case of [EMAIL PROTECTED]
org.apache.framework.configuration.impl.DefaultConfigurationBuilder}, the
namespace will
* be the URI associated with the XML element. Eg.,:</p>
* <pre>
* <foo xmlns:x="http://blah.com">
* <x:bar/>
* </foo>
* </pre>
* <p>The namespace of <code>foo</code> will be "", and the namespace of
* <code>bar</code> will be "http://blah.com";.</p>
*
* @return a String identifying the namespace of this Configuration.
* @exception ConfigurationException if an error occurs
* @since 4.1
*/
String getNamespace() throws ConfigurationException;
/**
* Return a new <code>Configuration</code> instance encapsulating the
* specified child node.
* <p>
* If no such child node exists, an empty <code>Configuration</code> will
be
* returned, allowing constructs such as
* <code>conf.getChild("foo").getChild("bar").getChild("baz")[EMAIL
PROTECTED]
* #getValue(String) getValue}("default");</code>
* </p>
* <p>
* If you wish to get a <code>null</code> return when no element is
present,
* use [EMAIL PROTECTED] #getChild(String, boolean) getChild("foo",
<b>false</b>)}.
* </p>
*
* @param child The name of the child node.
* @return Configuration
* @pre child != null
* @post getConfiguration() != null
*
*/
Configuration getChild( String child );
/**
* Return a <code>Configuration</code> instance encapsulating the
specified
* child node.
*
* @param child The name of the child node.
* @param createNew If <code>true</code>, a new <code>Configuration</code>
* will be created and returned if the specified child does not exist. If
* <code>false</code>, <code>null</code> will be returned when the
specified
* child doesn't exist.
* @return Configuration
* @pre child != null
* @post getConfiguration() != null
*
*/
Configuration getChild( String child, boolean createNew );
/**
* Return an <code>Array</code> of <code>Configuration</code>
* elements containing all node children. The array order will reflect the
* order in the source config file.
*
* @return All child nodes
*/
Configuration[] getChildren();
/**
* Return an <code>Array</code> of <code>Configuration</code>
* elements containing all node children with the specified name. The
array
* order will reflect the order in the source config file.
*
* @param name The name of the children to get.
* @return The child nodes with name <code>name</code>
* @pre name != null
* @post getConfigurations() != null
*
*/
Configuration[] getChildren( String name );
/**
* Return an array of all attribute names.
* <p>
* <em>The order of attributes in this array can not be relied on.</em> As
* with XML, a <code>Configuration</code>'s attributes are an
* <em>unordered</em> set. If your code relies on order, eg
* <tt>conf.getAttributeNames()[0]</tt>, then it is liable to break if a
* different XML parser is used.
* </p>
* @return a <code>String[]</code> value
*/
String[] getAttributeNames();
/**
* Return the value of specified attribute.
*
* @param paramName The name of the parameter you ask the value of.
* @return String value of attribute.
* @exception ConfigurationException If no attribute with that name
exists.
* @pre paramName != null
* @post getAttribute != null
*
*/
String getAttribute( String paramName ) throws ConfigurationException;
/**
* Return the <code>int</code> value of the specified attribute contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return int value of attribute
* @exception ConfigurationException If no parameter with that name
exists.
* or if conversion to <code>int</code>
fails.
* @pre paramName != null
* @post getAttributeAsInteger() != null
*
*/
int getAttributeAsInteger( String paramName ) throws
ConfigurationException;
/**
* Returns the value of the attribute specified by its name as a
* <code>long</code>.
*
* @param name The name of the parameter you ask the value of.
* @return long value of attribute
* @exception ConfigurationException If no parameter with that name
exists.
* or if conversion to
<code>long</code> fails.
* @pre paramName != null
* @post getAttributeAsLong() != null
*
*/
long getAttributeAsLong( String name ) throws ConfigurationException;
/**
* Return the <code>float</code> value of the specified parameter
contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return float value of attribute
* @exception ConfigurationException If no parameter with that name
exists.
* or if conversion to
<code>float</code> fails.
* @pre paramName != null
* @post getAttributeAsFloat() != null
*
*/
float getAttributeAsFloat( String paramName ) throws
ConfigurationException;
/**
* Return the <code>boolean</code> value of the specified parameter
contained
* in this node.
*
* @param paramName The name of the parameter you ask the value of.
* @return boolean value of attribute
* @exception ConfigurationException If no parameter with that name
exists.
* or if conversion to
<code>boolean</code> fails.
* @pre paramName != null
* @post getAttributeAsBoolean() != null
*
*/
boolean getAttributeAsBoolean( String paramName ) throws
ConfigurationException;
/**
* Return the <code>String</code> value of the node.
*
* @return the value of the node.
* @exception ConfigurationException if an error occurs
* @post getValue() != null
*
*/
String getValue() throws ConfigurationException;
/**
* Return the <code>int</code> value of the node.
*
* @return the value of the node.
*
* @exception ConfigurationException If conversion to <code>int</code>
fails.
* @post getValueAsInteger() != null
*
*/
int getValueAsInteger() throws ConfigurationException;
/**
* Return the <code>float</code> value of the node.
*
* @return the value of the node.
* @exception ConfigurationException If conversion to <code>float</code>
fails.
* @post getValueAsFloat() != null
*
*/
float getValueAsFloat() throws ConfigurationException;
/**
* Return the <code>boolean</code> value of the node.
*
* @return the value of the node.
* @exception ConfigurationException If conversion to
<code>boolean</code> fails.
* @post getValueAsBoolean() != null
*
*/
boolean getValueAsBoolean() throws ConfigurationException;
/**
* Return the <code>long</code> value of the node.
*
* @return the value of the node.
* @exception ConfigurationException If conversion to <code>long</code>
fails.
* @post getValueAsLong() != null
*
*/
long getValueAsLong() throws ConfigurationException;
/**
* Returns the value of the configuration element as a
<code>String</code>.
* If the configuration value is not set, the default value will be
* used.
*
* @param defaultValue The default value desired.
* @return String value of the <code>Configuration</code>, or default
* if none specified.
* @pre defaultValue != null
* @post getValue(defaultValue) != null
*
*/
String getValue( String defaultValue );
/**
* Returns the value of the configuration element as an <code>int</code>.
* If the configuration value is not set, the default value will be
* used.
*
* @param defaultValue The default value desired.
* @return int value of the <code>Configuration</code>, or default
* if none specified.
* @pre defaultValue != null
* @post getValueAsInteger(defaultValue) != null
*
*/
int getValueAsInteger( int defaultValue );
/**
* Returns the value of the configuration element as a <code>long</code>.
* If the configuration value is not set, the default value will be
* used.
*
* @param defaultValue The default value desired.
* @return long value of the <code>Configuration</code>, or default
* if none specified.
* @pre defaultValue != null
* @post getValueAsLong(defaultValue) != null
*
*/
long getValueAsLong( long defaultValue );
/**
* Returns the value of the configuration element as a <code>float</code>.
* If the configuration value is not set, the default value will be
* used.
*
* @param defaultValue The default value desired.
* @return float value of the <code>Configuration</code>, or default
* if none specified.
* @pre defaultValue != null
* @post getValueAsFloat(defaultValue) != null
*
*/
float getValueAsFloat( float defaultValue );
/**
* Returns the value of the configuration element as a
<code>boolean</code>.
* If the configuration value is not set, the default value will be
* used.
*
* @param defaultValue The default value desired.
* @return boolean value of the <code>Configuration</code>, or default
* if none specified.
* @pre defaultValue != null
* @post getValueAsBoolean(defaultValue) != null
*
*/
boolean getValueAsBoolean( boolean defaultValue );
/**
* Returns the value of the attribute specified by its name as a
* <code>String</code>, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return String value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
* @pre name != null
* @pre defaultValue != null
* @pre name != null
* @pre defaultValue != null
* @post getAttribute(name, defaultValue) != null
*
*/
String getAttribute( String name, String defaultValue );
/**
* Returns the value of the attribute specified by its name as a
* <code>int</code>, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return int value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
* @pre name != null
* @pre defaultValue != null
* @pre name != null
* @pre defaultValue != null
* @post getAttributeAsInteger(name, defaultValue) != null
*
*/
int getAttributeAsInteger( String name, int defaultValue );
/**
* Returns the value of the attribute specified by its name as a
* <code>long</code>, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return long value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
* @pre name != null
* @pre defaultValue != null
* @pre name != null
* @pre defaultValue != null
* @post getAttributeAsLong(name, defaultValue) != null
*
*/
long getAttributeAsLong( String name, long defaultValue );
/**
* Returns the value of the attribute specified by its name as a
* <code>float</code>, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return float value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
* @pre name != null
* @pre defaultValue != null
* @pre name != null
* @pre defaultValue != null
* @post getAttributeAsFloat(name, defaultValue) != null
*
*/
float getAttributeAsFloat( String name, float defaultValue );
/**
* Returns the value of the attribute specified by its name as a
* <code>boolean</code>, or the default value if no attribute by
* that name exists or is empty.
*
* @param name The name of the attribute you ask the value of.
* @param defaultValue The default value desired.
* @return boolean value of attribute. It will return the default
* value if the named attribute does not exist, or if
* the value is not set.
* @pre name != null
* @pre defaultValue != null
* @pre name != null
* @pre defaultValue != null
* @post getAttributeAsBoolean(name, defaultValue) != null
*
*/
boolean getAttributeAsBoolean( String name, boolean defaultValue );
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/ConfigurationException.java
Index: ConfigurationException.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.framework.configuration;
/**
* Thrown when a <code>Configurable</code> component cannot be configured
* properly, or if a value cannot be retrieved properly.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
*/
public class ConfigurationException
extends Exception
{
/**
* The Throwable that caused this exception to be thrown.
*/
private final Throwable m_throwable;
/**
* Construct a new <code>ConfigurationException</code> instance.
*
* @param message The detail message for this exception.
*/
public ConfigurationException( final String message )
{
this( message, null );
}
/**
* Construct a new <code>ConfigurationException</code> instance.
*
* @param message The detail message for this exception.
* @param throwable the root cause of the exception
*/
public ConfigurationException( final String message, final Throwable
throwable )
{
super( message );
m_throwable = throwable;
}
/**
* Retrieve root cause of the exception.
*
* @return the root cause
*/
public final Throwable getCause()
{
return m_throwable;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/package.html
Index: package.html
===================================================================
<body bgcolor="white">
Component configuration interfaces and XML-based implementations.
<br><br>
<p>The <code>org.apache.avalon.framework.configuration</code> package
contains primarily:</p>
<ul>
<li>The <a href="Configurable.html">Configurable</a> interface, which a
Component implements
if it needs to be configured with externally-specified data before it
is initialized.
</li>
<li>The <a href="Configuration.html">Configuration</a> interface, an
implementation of which
will be passed to Components that implement <a
href="Configurable.html">Configurable</a>.</li>
<li>The <a href="Reconfigurable.html">Reconfigurable</a> interface,
which Components implement if
they need to be reconfigured at runtime.</li>
<li>Various classes providing the default XML-based implementation of <a
href="Configuration.html">Configuration</a>. The mapping from XML to
Configuration tree is
described in <a
href="DefaultConfigurationBuilder.html">DefaultConfigurationBuilder</a>.
</ul>
</body>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/DefaultConfiguration.java
Index: DefaultConfiguration.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.framework.configuration.impl;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.HashMap;
import org.apache.framework.configuration.AbstractConfiguration;
import org.apache.framework.configuration.Configuration;
import org.apache.framework.configuration.ConfigurationException;
/**
* This is the default <code>Configuration</code> implementation.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @version 1.0
*/
public class DefaultConfiguration
extends AbstractConfiguration
implements Serializable
{
/**
* An empty (length zero) array of configuration objects.
*/
protected static final Configuration[] EMPTY_ARRAY = new Configuration[
0 ];
private final String m_name;
private final String m_location;
private final String m_namespace;
private final String m_prefix;
private HashMap m_attributes;
private ArrayList m_children;
private String m_value;
private boolean m_readOnly;
/**
* Create a new <code>DefaultConfiguration</code> instance.
* @param name a <code>String</code> value
* @param location a <code>String</code> value
*/
public DefaultConfiguration( final String name, final String location )
{
this( name, location, "", "" );
}
/**
* Create a new <code>DefaultConfiguration</code> instance.
* @param name config node name
* @param location Builder-specific locator string
* @param ns Namespace string (typically a URI). Should not be null; use
""
* if no namespace.
* @param prefix A short string prefixed to element names, associating
* elements with a longer namespace string. Should not be null; use "" if
no
* namespace.
*/
public DefaultConfiguration( final String name,
final String location,
final String ns,
final String prefix )
{
m_name = name;
m_location = location;
m_namespace = ns;
m_prefix = prefix; // only used as a serialization hint. Cannot be
null
}
/**
* Returns the name of this configuration element.
* @return a <code>String</code> value
*/
public String getName()
{
return m_name;
}
/**
* Returns the namespace of this configuration element
* @return a <code>String</code> value
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public String getNamespace() throws ConfigurationException
{
if( null != m_namespace )
{
return m_namespace;
}
else
{
throw new ConfigurationException
( "No namespace (not even default \"\") is associated with
the "+
"configuration element \"" +
getName() +
"\" at " + getLocation() );
}
}
/**
* Returns the prefix of the namespace
* @return a <code>String</code> value
* @exception org.apache.framework.configuration.ConfigurationException
if prefix is not present (<code>null</code>).
*/
protected String getPrefix() throws ConfigurationException
{
if( null != m_prefix )
{
return m_prefix;
}
else
{
throw new ConfigurationException
( "No prefix (not even default \"\") is associated with the "+
"configuration element \"" +
getName() +
"\" at " + getLocation() );
}
}
/**
* Returns a description of location of element.
* @return a <code>String</code> value
*/
public String getLocation()
{
return m_location;
}
/**
* Returns the value of the configuration element as a
<code>String</code>.
*
* @return a <code>String</code> value
* @exception org.apache.framework.configuration.ConfigurationException
If the value is not present.
*/
public String getValue() throws ConfigurationException
{
if( null != m_value )
{
return m_value;
}
else
{
throw new ConfigurationException( "No value is associated with
the "+
"configuration element \"" +
getName() +
"\" at " + getLocation() );
}
}
/**
* Return an array of all attribute names.
* @return a <code>String[]</code> value
*/
public String[] getAttributeNames()
{
if( null == m_attributes )
{
return new String[ 0 ];
}
else
{
return (String[])m_attributes.keySet().toArray( new String[ 0 ] );
}
}
/**
* Return an <code>Iterator</code> of <code>Configuration<code>
* elements containing all node children.
*
* @return The child nodes with name
*/
public Configuration[] getChildren()
{
if( null == m_children )
{
return new Configuration[ 0 ];
}
else
{
return (Configuration[])m_children.toArray( new Configuration[ 0
] );
}
}
/**
* Returns the value of the attribute specified by its name as a
* <code>String</code>.
*
* @param name a <code>String</code> value
* @return a <code>String</code> value
* @exception org.apache.framework.configuration.ConfigurationException
If the attribute is not present.
*/
public String getAttribute( final String name )
throws ConfigurationException
{
final String value =
(null != m_attributes) ? (String)m_attributes.get( name ) : null;
if( null != value )
{
return value;
}
else
{
throw new ConfigurationException( "No attribute named \"" + name
+ "\" is " +
"associated with the
configuration element \"" +
getName() + "\" at " +
getLocation() );
}
}
/**
* Return the first <code>Configuration</code> object child of this
* associated with the given name.
* @param name a <code>String</code> value
* @param createNew a <code>boolean</code> value
* @return a <code>Configuration</code> value
*/
public Configuration getChild( final String name, final boolean createNew
)
{
if( null != m_children )
{
final int size = m_children.size();
for( int i = 0; i < size; i++ )
{
final Configuration configuration =
(Configuration)m_children.get( i );
if( name.equals( configuration.getName() ) )
{
return configuration;
}
}
}
if( createNew )
{
return new DefaultConfiguration( name, "-" );
}
else
{
return null;
}
}
/**
* Return an <code>Enumeration</code> of <code>Configuration</code>
objects
* children of this associated with the given name.
* <br>
* The returned <code>Enumeration</code> may be empty.
*
* @param name The name of the required children
<code>Configuration</code>.
* @return a <code>Configuration[]</code> value
*/
public Configuration[] getChildren( final String name )
{
if( null == m_children )
{
return new Configuration[ 0 ];
}
else
{
final ArrayList children = new ArrayList();
final int size = m_children.size();
for( int i = 0; i < size; i++ )
{
final Configuration configuration =
(Configuration)m_children.get( i );
if( name.equals( configuration.getName() ) )
{
children.add( configuration );
}
}
return (Configuration[])children.toArray( new Configuration[ 0 ]
);
}
}
/**
* Append data to the value of this configuration element.
*
* @param value a <code>String</code> value
* @deprecated Use setValue() instead
*/
public void appendValueData( final String value )
{
checkWriteable();
if( null == m_value )
{
m_value = value;
}
else
{
m_value += value;
}
}
/**
* Set the value of this <code>Configuration</code> object to the
specified string.
*
* @param value a <code>String</code> value
*/
public void setValue( final String value )
{
checkWriteable();
m_value = value;
}
/**
* Set the value of the specified attribute to the specified string.
*
* @param name name of the attribute to set
* @param value a <code>String</code> value
*/
public void setAttribute( final String name, final String value )
{
checkWriteable();
if( null == m_attributes )
{
m_attributes = new HashMap();
}
m_attributes.put( name, value );
}
/**
* Add an attribute to this configuration element, returning its old
* value or <b>null</b>.
*
* @param name a <code>String</code> value
* @param value a <code>String</code> value
* @return a <code>String</code> value
* @deprecated Use setAttribute() instead
*/
public String addAttribute( final String name, String value )
{
checkWriteable();
if( null == m_attributes )
{
m_attributes = new HashMap();
}
return (String) m_attributes.put( name, value );
}
/**
* Add a child <code>Configuration</code> to this configuration element.
* @param configuration a <code>Configuration</code> value
*/
public void addChild( final Configuration configuration )
{
checkWriteable();
if( null == m_children )
{
m_children = new ArrayList();
}
m_children.add( configuration );
}
/**
* Remove a child <code>Configuration</code> to this configuration
element.
* @param configuration a <code>Configuration</code> value
*/
public void removeChild( final Configuration configuration )
{
checkWriteable();
if( null == m_children )
{
return;
}
m_children.remove( configuration );
}
/**
* Return count of children.
* @return an <code>int</code> value
*/
public int getChildCount()
{
if( null == m_children )
{
return 0;
}
return m_children.size();
}
/**
* Make this configuration read-only.
*
*/
public void makeReadOnly()
{
m_readOnly = true;
}
/**
* heck if this configuration is writeable.
*
* @exception java.lang.IllegalStateException if this configuration s
read-only
*/
protected final void checkWriteable()
throws IllegalStateException
{
if( m_readOnly )
{
throw new IllegalStateException
( "Configuration is read only and can not be modified" );
}
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/DefaultConfigurationBuilder.java
Index: DefaultConfigurationBuilder.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.framework.configuration.impl;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
import org.apache.framework.configuration.Configuration;
import org.apache.framework.configuration.ConfigurationException;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
/**
* A DefaultConfigurationBuilder builds <code>Configuration</code>s from XML,
* via a SAX2 compliant parser.
*
* <p>
* XML namespace support is optional, and disabled by default to preserve
* backwards-compatibility. To enable it, pass the [EMAIL PROTECTED]
* #DefaultConfigurationBuilder(boolean)} constructor the flag
<code>true</code>, or pass
* a namespace-enabled <code>XMLReader</code> to the [EMAIL PROTECTED]
* #DefaultConfigurationBuilder(XMLReader)} constructor.
* </p>
* <p>
* The mapping from XML namespaces to [EMAIL PROTECTED]
org.apache.framework.configuration.Configuration} namespaces is pretty
* straightforward, with one caveat: attribute namespaces are (deliberately)
not
* supported. Enabling namespace processing has the following effects:</p>
* <ul>
* <li>Attributes starting with <code>xmlns:</code> are interpreted as
* declaring a prefix:namespaceURI mapping, and won't result in the creation
of
* <code>xmlns</code>-prefixed attributes in the <code>Configuration</code>.
* </li>
* <li>
* Prefixed XML elements, like <tt><doc:title
xmlns:doc="http://foo.com">,</tt>
* will result in a <code>Configuration</code> with <code>[EMAIL PROTECTED]
* Configuration#getName getName()}.equals("title")</code> and <code>[EMAIL
PROTECTED]
* Configuration#getNamespace
getNamespace()}.equals("http://foo.com";)</code>.
* </li>
* </ul>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @version 1.0
*/
public class DefaultConfigurationBuilder
{
private SAXConfigurationHandler m_handler;
private XMLReader m_parser;
/**
* Create a Configuration Builder with a default XMLReader that ignores
* namespaces. In order to enable namespaces, use either the constructor
* that has a boolean or that allows you to pass in your own
* namespace-enabled XMLReader.
*/
public DefaultConfigurationBuilder()
{
this( false );
}
/**
* Create a Configuration Builder, specifying a flag that determines
* namespace support.
*
* @param enableNamespaces If <code>true</code>, a namespace-aware
* <code>SAXParser</code> is used. If <code>false</code>, the default JAXP
* <code>SAXParser</code> (without namespace support) is used.
*/
public DefaultConfigurationBuilder( final boolean enableNamespaces )
{
//yaya the bugs with some compilers and final variables ..
try
{
final SAXParserFactory saxParserFactory =
SAXParserFactory.newInstance();
if ( enableNamespaces )
{
saxParserFactory.setNamespaceAware(true);
}
final SAXParser saxParser = saxParserFactory.newSAXParser();
this.setParser(saxParser.getXMLReader());
}
catch( final Exception se )
{
throw new Error( "Unable to setup SAX parser" + se );
}
}
/**
* Create a Configuration Builder with your own XMLReader.
* @param parser an <code>XMLReader</code>
*/
public DefaultConfigurationBuilder( XMLReader parser )
{
this.setParser(parser);
}
/**
* Internally sets up the XMLReader
*/
private void setParser(XMLReader parser)
{
m_parser = parser;
m_handler = getHandler();
m_parser.setContentHandler( m_handler );
m_parser.setErrorHandler( m_handler );
}
/**
* Get a SAXConfigurationHandler for your configuration reading.
* @return a <code>SAXConfigurationHandler</code>
*/
protected SAXConfigurationHandler getHandler()
{
try
{
if ( m_parser.getFeature(
"http://xml.org/sax/features/namespaces"; ) )
{
return new NamespacedSAXConfigurationHandler();
}
}
catch ( Exception e )
{
// ignore error and fall through to the non-namespaced version
}
return new SAXConfigurationHandler();
}
/**
* Build a configuration object from a file using a filename.
* @param filename name of the file
* @return a <code>Configuration</code> object
* @exception SAXException if a parsing error occurs
* @exception java.io.IOException if an I/O error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public Configuration buildFromFile( final String filename )
throws SAXException, IOException, ConfigurationException
{
return buildFromFile( new File( filename ) );
}
/**
* Build a configuration object from a file using a File object.
* @param file a <code>File</code> object
* @return a <code>Configuration</code> object
* @exception SAXException if a parsing error occurs
* @exception java.io.IOException if an I/O error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public Configuration buildFromFile( final File file )
throws SAXException, IOException, ConfigurationException
{
synchronized(this)
{
m_handler.clear();
m_parser.parse( file.toURL().toString() );
return m_handler.getConfiguration();
}
}
/**
* Build a configuration object using an InputStream.
* @param inputStream an <code>InputStream</code> value
* @return a <code>Configuration</code> object
* @exception SAXException if a parsing error occurs
* @exception java.io.IOException if an I/O error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public Configuration build( final InputStream inputStream )
throws SAXException, IOException, ConfigurationException
{
return build( new InputSource( inputStream ) );
}
/**
* Build a configuration object using an URI
* @param uri a <code>String</code> value
* @return a <code>Configuration</code> object
* @exception SAXException if a parsing error occurs
* @exception java.io.IOException if an I/O error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public Configuration build( final String uri )
throws SAXException, IOException, ConfigurationException
{
return build( new InputSource( uri ) );
}
/**
* Build a configuration object using an XML InputSource object
* @param input an <code>InputSource</code> value
* @return a <code>Configuration</code> object
* @exception SAXException if a parsing error occurs
* @exception java.io.IOException if an I/O error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public Configuration build( final InputSource input )
throws SAXException, IOException, ConfigurationException
{
synchronized(this)
{
m_handler.clear();
m_parser.parse( input );
return m_handler.getConfiguration();
}
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/DefaultConfigurationSerializer.java
Index: DefaultConfigurationSerializer.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.framework.configuration.impl;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.net.URL;
import java.util.Properties;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.sax.SAXTransformerFactory;
import javax.xml.transform.sax.TransformerHandler;
import javax.xml.transform.stream.StreamResult;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.AttributesImpl;
import org.xml.sax.helpers.NamespaceSupport;
import org.apache.framework.configuration.Configuration;
import org.apache.framework.configuration.ConfigurationException;
import org.apache.framework.configuration.AbstractConfiguration;
/**
* A ConfigurationSerializer serializes configurations via SAX2 compliant
parser.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @version 1.0
*/
public class DefaultConfigurationSerializer
{
private SAXTransformerFactory m_tfactory;
private TransformerHandler m_handler;
private OutputStream m_out;
private Properties m_format = new Properties();
private NamespaceSupport m_namespaceSupport = new NamespaceSupport();
/**
* Build a ConfigurationSerializer
*/
public DefaultConfigurationSerializer()
{
getTransformerFactory();
}
/**
* Sets the Serializer's use of indentation. This will cause linefeeds
to be added
* after each element, but it does not add any indentation via spaces.
* @param indent a <code>boolean</code> value
*/
public void setIndent( boolean indent )
{
if ( indent )
{
m_format.put( OutputKeys.INDENT, "yes" );
}
else
{
m_format.put( OutputKeys.INDENT, "no" );
}
}
/**
* Internally set the output strream we will be using.
* @param out an <code>OutputStream</code> value
*/
protected void setOutputStream( final OutputStream out )
{
try
{
m_out = out;
m_handler = getTransformerFactory().newTransformerHandler();
m_format.put(OutputKeys.METHOD,"xml");
m_handler.setResult(new StreamResult(out));
m_handler.getTransformer().setOutputProperties( m_format );
}
catch( final Exception e )
{
throw new RuntimeException( e.toString() );
}
}
/**
* Get the SAXTransformerFactory so we can get a serializer without being
* tied to one vendor.
* @return a <code>SAXTransformerFactory</code> value
*/
protected SAXTransformerFactory getTransformerFactory()
{
if(m_tfactory == null)
{
m_tfactory = (SAXTransformerFactory)
TransformerFactory.newInstance();
}
return m_tfactory;
}
/**
* Start the serialization process. The output stream
<strong>must</strong>
* be set before calling this method.
* @param source a <code>Configuration</code> value
* @exception SAXException if an error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
protected void serialize( final Configuration source )
throws SAXException, ConfigurationException
{
m_namespaceSupport.reset();
m_handler.startDocument();
serializeElement(source);
m_handler.endDocument();
}
/**
* Serialize each Configuration element. This method is called
recursively.
* @param element a <code>Configuration</code> value
* @exception SAXException if an error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
protected void serializeElement( final Configuration element )
throws SAXException, ConfigurationException
{
m_namespaceSupport.pushContext();
AttributesImpl attr = new AttributesImpl();
String[] attrNames = element.getAttributeNames();
if (null != attrNames)
{
for (int i = 0; i < attrNames.length; i++)
{
attr.addAttribute("", // namespace URI
attrNames[i], // local name
attrNames[i], // qName
"CDATA", // type
element.getAttribute(attrNames[i], "") //
value
);
}
}
final String nsURI = element.getNamespace();
String nsPrefix = "";
if ( element instanceof AbstractConfiguration )
{
nsPrefix = ((AbstractConfiguration) element).getPrefix();
}
// nsPrefix is guaranteed to be non-null at this point.
boolean nsWasDeclared = false;
final String existingURI = m_namespaceSupport.getURI( nsPrefix );
// ie, there is no existing URI declared for this prefix or we're
// remapping the prefix to a different URI
if ( existingURI == null || !existingURI.equals( nsURI ) )
{
nsWasDeclared = true;
if (nsPrefix.equals("") && nsURI.equals(""))
{
// implicit mapping; don't need to declare
}
else if (nsPrefix.equals(""))
{
// (re)declare the default namespace
attr.addAttribute("", "xmlns", "xmlns", "CDATA", nsURI);
}
else
{
// (re)declare a mapping from nsPrefix to nsURI
attr.addAttribute("", "xmlns:"+nsPrefix, "xmlns:"+nsPrefix,
"CDATA", nsURI);
}
m_handler.startPrefixMapping( nsPrefix, nsURI );
m_namespaceSupport.declarePrefix( nsPrefix, nsURI );
}
String localName = element.getName();
String qName = element.getName();
if ( nsPrefix == null || nsPrefix.length() == 0 )
{
qName = localName;
}
else
{
qName = nsPrefix + ":" + localName;
}
m_handler.startElement(nsURI, localName, qName, attr);
String value = element.getValue(null);
if (null == value)
{
Configuration[] children = element.getChildren();
for (int i = 0; i < children.length; i++)
{
serializeElement(children[i]);
}
}
else
{
m_handler.characters(value.toCharArray(), 0, value.length());
}
m_handler.endElement(nsURI, localName, qName);
if ( nsWasDeclared )
{
m_handler.endPrefixMapping( nsPrefix );
}
m_namespaceSupport.popContext();
}
/**
* Serialize the configuration object to a file using a filename.
* @param filename a <code>String</code> value
* @param source a <code>Configuration</code> value
* @exception SAXException if an error occurs
* @exception java.io.IOException if an error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public void serializeToFile( final String filename, final Configuration
source )
throws SAXException, IOException, ConfigurationException
{
serializeToFile( new File( filename ), source );
}
/**
* Serialize the configuration object to a file using a File object.
* @param file a <code>File</code> value
* @param source a <code>Configuration</code> value
* @exception SAXException if an error occurs
* @exception java.io.IOException if an error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public void serializeToFile( final File file, final Configuration source )
throws SAXException, IOException, ConfigurationException
{
serialize( new FileOutputStream( file ), source );
}
/**
* Serialize the configuration object to an output stream.
* @param outputStream an <code>OutputStream</code> value
* @param source a <code>Configuration</code> value
* @exception SAXException if an error occurs
* @exception java.io.IOException if an error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public void serialize( final OutputStream outputStream, final
Configuration source )
throws SAXException, IOException, ConfigurationException
{
synchronized(this)
{
setOutputStream( outputStream );
serialize( source );
}
}
/**
* Serialize the configuration object to an output stream derived from an
* URI. The URI must be resolveable by the <code>java.net.URL</code>
object.
* @param uri a <code>String</code> value
* @param source a <code>Configuration</code> value
* @exception SAXException if an error occurs
* @exception java.io.IOException if an error occurs
* @exception org.apache.framework.configuration.ConfigurationException
if an error occurs
*/
public void serialize( final String uri, final Configuration source )
throws SAXException, IOException, ConfigurationException
{
serialize( new URL( uri ).openConnection().getOutputStream(), source
);
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/NamespacedSAXConfigurationHandler.java
Index: NamespacedSAXConfigurationHandler.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.framework.configuration.impl;
import java.util.ArrayList;
import java.util.Iterator;
import org.xml.sax.Attributes;
import org.xml.sax.Locator;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.helpers.NamespaceSupport;
import org.xml.sax.helpers.AttributesImpl;
import org.apache.framework.configuration.impl.DefaultConfiguration;
import org.apache.framework.configuration.Configuration;
/**
* A SAXConfigurationHandler helps build Configurations out of sax events,
* including namespace information.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @version 1.0
*/
public class NamespacedSAXConfigurationHandler
extends SAXConfigurationHandler
{
private final ArrayList m_elements = new ArrayList();
private final ArrayList m_prefixes = new ArrayList();
private Configuration m_configuration;
private Locator m_locator;
private NamespaceSupport m_namespaceSupport = new
NamespaceSupport();
/**
* Get the configuration object that was built.
*
* @return a <code>Configuration</code> object
*/
public Configuration getConfiguration()
{
return m_configuration;
}
/**
* Clears all data from this configuration handler.
*/
public void clear()
{
m_elements.clear();
Iterator i = m_prefixes.iterator();
while ( i.hasNext() )
{
( (ArrayList) i.next() ).clear();
}
m_prefixes.clear();
m_locator = null;
}
/**
* Set the document <code>Locator</code> to use.
*
* @param locator a <code>Locator</code> value
*/
public void setDocumentLocator( final Locator locator )
{
m_locator = locator;
}
/**
* Handling hook for starting the document parsing.
*
* @exception SAXException if an error occurs
*/
public void startDocument()
throws SAXException
{
m_namespaceSupport.reset();
super.startDocument();
}
/**
* Handling hook for ending the document parsing.
*
* @exception SAXException if an error occurs
*/
public void endDocument()
throws SAXException
{
super.endDocument();
m_namespaceSupport.reset();
}
/**
* Handling hook for character data.
*
* @param ch a <code>char[]</code> of data
* @param start offset in the character array from which to start reading
* @param end length of character data
* @exception SAXException if an error occurs
*/
public void characters( final char[] ch, int start, int end )
throws SAXException
{
String value = (new String( ch, start, end )).trim();
if( value.equals( "" ) )
{
return;
}
final DefaultConfiguration configuration =
(DefaultConfiguration)m_elements.get( m_elements.size() - 1 );
if( 0 != configuration.getChildCount() )
{
throw new SAXException( "Not allowed to define mixed content in
the " +
"element " + configuration.getName() + "
at " +
configuration.getLocation() );
}
value = configuration.getValue( "" ) + value;
configuration.setValue( value );
}
/**
* Handling hook for finishing parsing of an element.
*
* @param namespaceURI a <code>String</code> value
* @param localName a <code>String</code> value
* @param rawName a <code>String</code> value
* @exception SAXException if an error occurs
*/
public void endElement( final String namespaceURI,
final String localName,
final String rawName )
throws SAXException
{
final int location = m_elements.size() - 1;
final Object object = m_elements.remove( location );
final ArrayList prefixes = (ArrayList) m_prefixes.remove( location );
final Iterator i = prefixes.iterator();
while ( i.hasNext() )
{
endPrefixMapping( (String) i.next() );
}
prefixes.clear();
if( 0 == location )
{
m_configuration = (Configuration)object;
}
m_namespaceSupport.popContext();
}
/**
* Create a new <code>DefaultConfiguration</code> with the specified
* local name, namespace, and location.
*
* @param localName a <code>String</code> value
* @param namespaceURI a <code>String</code> value
* @param location a <code>String</code> value
* @return a <code>DefaultConfiguration</code> value
*/
protected DefaultConfiguration createConfiguration( final String
localName,
final String
namespaceURI,
final String location
)
{
String prefix = m_namespaceSupport.getPrefix( namespaceURI );
if (prefix == null)
{
prefix = "";
}
return new DefaultConfiguration( localName, location, namespaceURI,
prefix );
}
/**
* Handling hook for starting parsing of an element.
*
* @param namespaceURI a <code>String</code> value
* @param localName a <code>String</code> value
* @param rawName a <code>String</code> value
* @param attributes an <code>Attributes</code> value
* @exception SAXException if an error occurs
*/
public void startElement( final String namespaceURI,
final String localName,
final String rawName,
final Attributes attributes )
throws SAXException
{
m_namespaceSupport.pushContext();
final ArrayList prefixes = new ArrayList();
AttributesImpl componentAttr = new AttributesImpl();
for (int i = 0; i < attributes.getLength(); i++)
{
if ( attributes.getQName(i).startsWith("xmlns") )
{
prefixes.add( attributes.getLocalName(i) );
this.startPrefixMapping( attributes.getLocalName(i),
attributes.getValue(i) );
}
else
{
componentAttr.addAttribute( attributes.getURI( i ),
attributes.getLocalName( i ),
attributes.getQName( i ),
attributes.getType( i ),
attributes.getValue( i ) );
}
}
final DefaultConfiguration configuration =
createConfiguration( localName, namespaceURI, getLocationString()
);
final int size = m_elements.size() - 1;
if( size > -1 )
{
final DefaultConfiguration parent =
(DefaultConfiguration)m_elements.get( size );
if( null != parent.getValue( null ) )
{
throw new SAXException( "Not allowed to define mixed content
in the " +
"element " + parent.getName() + " at
" +
parent.getLocation() );
}
parent.addChild( configuration );
}
m_elements.add( configuration );
m_prefixes.add( prefixes );
final int attributesSize = componentAttr.getLength();
for( int i = 0; i < attributesSize; i++ )
{
final String name = componentAttr.getQName( i );
final String value = componentAttr.getValue( i );
configuration.setAttribute( name, value );
}
}
/**
* This just throws an exception on a parse error.
* @param exception the parse error
* @exception SAXException if an error occurs
*/
public void error( final SAXParseException exception )
throws SAXException
{
throw exception;
}
/**
* This just throws an exception on a parse error.
* @param exception the parse error
* @exception SAXException if an error occurs
*/
public void warning( final SAXParseException exception )
throws SAXException
{
throw exception;
}
/**
* This just throws an exception on a parse error.
* @param exception the parse error
* @exception SAXException if an error occurs
*/
public void fatalError( final SAXParseException exception )
throws SAXException
{
throw exception;
}
/**
* Returns a string showing the current system ID, line number and column
number.
*
* @return a <code>String</code> value
*/
protected String getLocationString()
{
if( null == m_locator )
{
return "Unknown";
}
else
{
return
m_locator.getSystemId() + ":" +
m_locator.getLineNumber() + ":" +
m_locator.getColumnNumber();
}
}
/**
* Handling hook for starting prefix mapping.
*
* @param prefix a <code>String</code> value
* @param uri a <code>String</code> value
* @exception SAXException if an error occurs
*/
public void startPrefixMapping(String prefix, String uri)
throws SAXException
{
m_namespaceSupport.declarePrefix( prefix, uri );
super.startPrefixMapping( prefix, uri );
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/configuration/impl/SAXConfigurationHandler.java
Index: SAXConfigurationHandler.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.framework.configuration.impl;
import java.util.ArrayList;
import org.xml.sax.Attributes;
import org.xml.sax.ErrorHandler;
import org.xml.sax.Locator;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.helpers.DefaultHandler;
import org.apache.framework.configuration.impl.DefaultConfiguration;
import org.apache.framework.configuration.Configuration;
/**
* A SAXConfigurationHandler helps build Configurations out of sax events.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public class SAXConfigurationHandler
extends DefaultHandler
implements ErrorHandler
{
private final ArrayList m_elements = new ArrayList();
private Configuration m_configuration;
private Locator m_locator;
/**
* Get the configuration object that was built.
*
* @return a <code>Configuration</code> object
*/
public Configuration getConfiguration()
{
return m_configuration;
}
/**
* Clears all data from this configuration handler.
*/
public void clear()
{
m_elements.clear();
m_locator = null;
}
/**
* Set the document <code>Locator</code> to use.
*
* @param locator a <code>Locator</code> value
*/
public void setDocumentLocator( final Locator locator )
{
m_locator = locator;
}
/**
* Handling hook for character data.
*
* @param ch a <code>char[]</code> of data
* @param start offset in the character array from which to start reading
* @param end length of character data
* @exception SAXException if an error occurs
*/
public void characters( final char[] ch, int start, int end )
throws SAXException
{
String value = (new String( ch, start, end )).trim();
if( value.equals( "" ) )
{
return;
}
final DefaultConfiguration configuration =
(DefaultConfiguration)m_elements.get( m_elements.size() - 1 );
if( 0 != configuration.getChildCount() )
{
throw new SAXException( "Not allowed to define mixed content in
the " +
"element " + configuration.getName() + "
at " +
configuration.getLocation() );
}
value = configuration.getValue( "" ) + value;
configuration.setValue( value );
}
/**
* Handling hook for finishing parsing of an element.
*
* @param namespaceURI a <code>String</code> value
* @param localName a <code>String</code> value
* @param rawName a <code>String</code> value
* @exception SAXException if an error occurs
*/
public void endElement( final String namespaceURI,
final String localName,
final String rawName )
throws SAXException
{
final int location = m_elements.size() - 1;
final Object object = m_elements.remove( location );
if( 0 == location )
{
m_configuration = (Configuration)object;
}
}
/**
* Create a new <code>DefaultConfiguration</code> with the specified
* local name and location.
*
* @param localName a <code>String</code> value
* @param location a <code>String</code> value
* @return a <code>DefaultConfiguration</code> value
*/
protected DefaultConfiguration createConfiguration( final String
localName,
final String location
)
{
return new DefaultConfiguration( localName, location );
}
/**
* Handling hook for starting parsing of an element.
*
* @param namespaceURI a <code>String</code> value
* @param localName a <code>String</code> value
* @param rawName a <code>String</code> value
* @param attributes an <code>Attributes</code> value
* @exception SAXException if an error occurs
*/
public void startElement( final String namespaceURI,
final String localName,
final String rawName,
final Attributes attributes )
throws SAXException
{
final DefaultConfiguration configuration =
createConfiguration( rawName, getLocationString() );
final int size = m_elements.size() - 1;
if( size > -1 )
{
final DefaultConfiguration parent =
(DefaultConfiguration)m_elements.get( size );
if( null != parent.getValue( null ) )
{
throw new SAXException( "Not allowed to define mixed content
in the " +
"element " + parent.getName() + " at
" +
parent.getLocation() );
}
parent.addChild( configuration );
}
m_elements.add( configuration );
final int attributesSize = attributes.getLength();
for( int i = 0; i < attributesSize; i++ )
{
final String name = attributes.getQName( i );
final String value = attributes.getValue( i );
configuration.setAttribute( name, value );
}
}
/**
* This just throws an exception on a parse error.
* @param exception the parse error
* @exception SAXException if an error occurs
*/
public void error( final SAXParseException exception )
throws SAXException
{
throw exception;
}
/**
* This just throws an exception on a parse error.
* @param exception the parse error
* @exception SAXException if an error occurs
*/
public void warning( final SAXParseException exception )
throws SAXException
{
throw exception;
}
/**
* This just throws an exception on a parse error.
* @param exception the parse error
* @exception SAXException if an error occurs
*/
public void fatalError( final SAXParseException exception )
throws SAXException
{
throw exception;
}
/**
* Returns a string showing the current system ID, line number and column
number.
*
* @return a <code>String</code> value
*/
protected String getLocationString()
{
if( null == m_locator )
{
return "Unknown";
}
else
{
return
m_locator.getSystemId() + ":" +
m_locator.getLineNumber() + ":" +
m_locator.getColumnNumber();
}
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/Context.java
Index: Context.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.framework.context;
/**
* The context is the interface through which the Component
* and it's Container communicate.
*
* <p>Each Container-Component relationship will also involve defining
* a contract between two entities. This contract will specify the
* services, settings and information that is supplied by the
* Container to the Component.</p>
*
* <p>This relationship should be documented in a well known place.
* It is sometimes convenient to derive from Context to provide
* a particular style of Context for your Component-Container
* relationship. The documentation for required entries in context
* can then be defined there. (examples include MailetContext,
* BlockContext etc.)</p>
*
* <p>There are traditionally four differet types of Context that may be
* used in a system. These ideas are partially derived from linguistic theory
* and partially from tradition computer science;</p>
*
* <ol>
* <li>World Context / Per-Application context: This describes application
* wide settings/context. An example may be the working directory of the
* application.</li>
*
* <li>Person Context / Per-Component context: This contains context
* information specific to the component. An example may be the name of
* the component.</li>
*
* <li>Conversation Context / Per-Session context: This contains context
* information specific to the component. An example may be the IP address
* of the entity who you are talking to.</li>
*
* <li>Speach Act Context / Per-Request context: This contains information
* about a specific request in component. Example may include the parameter
* submitted to a particular web form or whatever.</li>
*
* </ol>
*
* <p>When we implement this (1) and (2) are generally merged into one
interface.
* For instance in the Pheonix Application Server there is a BlockContext.
Part
* of the BlockContext consists of two methods. One is getHomeDirectory() and
that
* belongs to (1) while the other is getName() which belongs to (2).</p>
*
* <p>(4) is usually passed into a service() style method as parameters.
Often it will
* named something like RequestObject. So you may have something like:</p>
*
* <pre>
* void doMagic( int param1, int param2, Context otherParamsInHere );
* </pre>
*
* <p>When (3) is needed in the system it is usually also passed into the a
serice method
* method, along with the request context (4). Alternatively it is made
available via the
* context representing (4).</p>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public interface Context
{
/**
* Retrieve an object from Context.
*
* @param key the key into context
* @return the object
* @exception ContextException if object not found. Note that this
* means that either Component is asking for invalid entry
* or the Container is not living up to contract.
*/
Object get( Object key )
throws ContextException;
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/ContextException.java
Index: ContextException.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.framework.context;
/**
* Exception signalling a badly formed Context.
*
* This can be thrown by Context object when a entry is not
* found. It can also be thrown manually in contextualize()
* when Component detects a malformed context value.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public class ContextException
extends Exception
{
/**
* The Throwable that caused this exception to be thrown.
*/
private final Throwable m_throwable;
/**
* Construct a new <code>ContextException</code> instance.
*
* @param message The detail message for this exception.
*/
public ContextException( final String message )
{
this( message, null );
}
/**
* Construct a new <code>ContextException</code> instance.
*
* @param message The detail message for this exception.
* @param throwable the root cause of the exception
*/
public ContextException( final String message, final Throwable throwable )
{
super( message );
m_throwable = throwable;
}
/**
* Retrieve root cause of the exception.
*
* @return the root cause
*/
public final Throwable getCause()
{
return m_throwable;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/Contextualizable.java
Index: Contextualizable.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.framework.context;
/**
* This inteface should be implemented by components that need
* a Context to work. Context contains runtime generated object
* provided by the Container to this Component.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
*/
public interface Contextualizable
{
/**
* Pass the Context to the component.
* This method is called after the Loggable.setLogger() (if present)
* method and before any other method.
*
* @param context the context
* @exception ContextException if context is invalid
*/
void contextualize( Context context )
throws ContextException;
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/package.html
Index: package.html
===================================================================
<body>
Interfaces and implementation of the Context model through which runtime
context can be applied by a manager to a component.
</body>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/context/impl/DefaultContext.java
Index: DefaultContext.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.framework.context.impl;
import java.util.Hashtable;
import java.util.Map;
import org.apache.framework.context.Context;
import org.apache.framework.context.ContextException;
/**
* Default implementation of Context.
* This implementation is a static hierarchial store.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public class DefaultContext
implements Context
{
private final Map m_contextData;
private final Context m_parent;
private boolean m_readOnly;
/**
* Create a Context with specified data and parent.
*
* @param contextData the context data
* @param parent the parent Context (may be null)
*/
public DefaultContext( final Map contextData, final Context parent )
{
m_parent = parent;
m_contextData = contextData;
}
/**
* Create a Context with specified data.
*
* @param contextData the context data
*/
public DefaultContext( final Map contextData )
{
this( contextData, null );
}
/**
* Create a Context with specified parent.
*
* @param parent the parent Context (may be null)
*/
public DefaultContext( final Context parent )
{
this( new Hashtable(), parent );
}
/**
* Create a Context with no parent.
*
*/
public DefaultContext()
{
this( (Context)null );
}
/**
* Retrieve an item from the Context.
*
* @param key the key of item
* @return the item stored in context
* @exception org.apache.framework.context.ContextException if item not
present
*/
public Object get( final Object key )
throws ContextException
{
final Object data = m_contextData.get( key );
if( null != data )
{
return data;
}
// If data was null, check the parent
if( null == m_parent )
{
// There was no parent, and no data
throw new ContextException( "Unable to locate " + key );
}
return m_parent.get( key );
}
/**
* Helper method fo adding items to Context.
*
* @param key the items key
* @param value the item
* @exception java.lang.IllegalStateException if context is read only
*/
public void put( final Object key, final Object value )
throws IllegalStateException
{
checkWriteable();
m_contextData.put( key, value );
}
/**
* Utility method to retrieve context data.
*
* @return the context data
*/
protected final Map getContextData()
{
return m_contextData;
}
/**
* Get parent context if any.
*
* @return the parent Context (may be null)
*/
protected final Context getParent()
{
return m_parent;
}
/**
* Make the context read-only.
* Any attempt to write to the context via put()
* will result in an IllegalStateException.
*/
public void makeReadOnly()
{
m_readOnly = true;
}
/**
* Utility method to check if context is writeable and if not throw
exception.
*
* @exception java.lang.IllegalStateException if context is read only
*/
protected final void checkWriteable()
throws IllegalStateException
{
if( m_readOnly )
{
throw new IllegalStateException( "Context is read only and can
not be modified" );
}
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/AbstractLogEnabled.java
Index: AbstractLogEnabled.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.framework.logger;
/**
* Utility class to allow construction of easy components that will perform
logging.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public abstract class AbstractLogEnabled
implements LogEnabled
{
///Base Logger instance
private Logger m_logger;
/**
* Set the components logger.
*
* @param logger the logger
*/
public void enableLogging( final Logger logger )
{
m_logger = logger;
}
/**
* Helper method to allow sub-classes to aquire logger.
* This method exists rather than exposing a member variable
* because it protects other users against future changes. It
* also means they do not have to use our naming convention.
*
* <p>There is no performance penalty as this is a final method
* and will be inlined by the JVM.</p>
*
* @return the Logger
*/
protected final Logger getLogger()
{
return m_logger;
}
/**
* Helper method to setup other components with same logger.
*
* @param component the component to pass logger object to
*/
protected void setupLogger( final Object component )
{
setupLogger( component, (String)null );
}
/**
* Helper method to setup other components with logger.
* The logger has the subcategory of this components logger.
*
* @param component the component to pass logger object to
* @param subCategory the subcategory to use (may be null)
*/
protected void setupLogger( final Object component, final String
subCategory )
{
Logger logger = m_logger;
if( null != subCategory )
{
logger = m_logger.getChildLogger( subCategory );
}
setupLogger( component, logger );
}
/**
* Helper method to setup other components with logger.
*
* @param component the component to pass logger object to
* @param logger the Logger
*/
protected void setupLogger( final Object component, final Logger logger )
{
if( component instanceof LogEnabled )
{
((LogEnabled)component).enableLogging( logger );
}
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/LogEnabled.java
Index: LogEnabled.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.framework.logger;
/**
* Components that need to log can implement this interface to
* be provided Loggers.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
*/
public interface LogEnabled
{
/**
* Provide component with a logger.
*
* @param logger the logger
*/
void enableLogging( Logger logger );
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/Logger.java
Index: Logger.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.framework.logger;
/**
* This is a facade for the different logging subsystems.
* It offers a simplified interface that follows IOC patterns
* and a simplified priority/level/severity abstraction.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public interface Logger
{
/**
* Log a debug message.
*
* @param message the message
*/
void debug( String message );
/**
* Log a debug message.
*
* @param message the message
* @param throwable the throwable
*/
void debug( String message, Throwable throwable );
/**
* Determine if messages of priority "debug" will be logged.
*
* @return true if "debug" messages will be logged
*/
boolean isDebugEnabled();
/**
* Log a info message.
*
* @param message the message
*/
void info( String message );
/**
* Log a info message.
*
* @param message the message
* @param throwable the throwable
*/
void info( String message, Throwable throwable );
/**
* Determine if messages of priority "info" will be logged.
*
* @return true if "info" messages will be logged
*/
boolean isInfoEnabled();
/**
* Log a warn message.
*
* @param message the message
*/
void warn( String message );
/**
* Log a warn message.
*
* @param message the message
* @param throwable the throwable
*/
void warn( String message, Throwable throwable );
/**
* Determine if messages of priority "warn" will be logged.
*
* @return true if "warn" messages will be logged
*/
boolean isWarnEnabled();
/**
* Log a error message.
*
* @param message the message
*/
void error( String message );
/**
* Log a error message.
*
* @param message the message
* @param throwable the throwable
*/
void error( String message, Throwable throwable );
/**
* Determine if messages of priority "error" will be logged.
*
* @return true if "error" messages will be logged
*/
boolean isErrorEnabled();
/**
* Log a fatalError message.
*
* @param message the message
*/
void fatalError( String message );
/**
* Log a fatalError message.
*
* @param message the message
* @param throwable the throwable
*/
void fatalError( String message, Throwable throwable );
/**
* Determine if messages of priority "fatalError" will be logged.
*
* @return true if "fatalError" messages will be logged
*/
boolean isFatalErrorEnabled();
/**
* Create a new child logger.
* The name of the child logger is [current-loggers-name].[passed-in-name]
* Throws <code>IllegalArgumentException</code> if name has an empty
element name
*
* @param name the subname of this logger
* @return the new logger
*/
Logger getChildLogger( String name );
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/package.html
Index: package.html
===================================================================
<body>
Abstract logging framework supporting pluggable logging mechanisms including
LogKit, Log4J and the JDK 1.4 logging infrastructure.
</body>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/ConsoleLogger.java
Index: ConsoleLogger.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.framework.logger.impl;
import org.apache.framework.logger.Logger;
/**
* Logger sending everything to the standard output streams.
* This is mainly for the cases when you have a utility that
* does not have a logger to supply.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Leo Sutic</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @version 1.0
*/
public final class ConsoleLogger
implements Logger
{
/** Typecode for debugging messages. */
public static final int LEVEL_DEBUG = 0;
/** Typecode for informational messages. */
public static final int LEVEL_INFO = 1;
/** Typecode for warning messages. */
public static final int LEVEL_WARN = 2;
/** Typecode for error messages. */
public static final int LEVEL_ERROR = 3;
/** Typecode for fatal error messages. */
public static final int LEVEL_FATAL = 4;
/** Typecode for disabled log levels. */
public static final int LEVEL_DISABLED = 5;
private final int m_logLevel;
/**
* Creates a new ConsoleLogger with the priority set to DEBUG.
*/
public ConsoleLogger()
{
this( LEVEL_DEBUG );
}
/**
* Creates a new ConsoleLogger.
* @param logLevel log level typecode
*/
public ConsoleLogger( final int logLevel )
{
m_logLevel = logLevel;
}
/**
* Logs a debugging message.
*
* @param message a <code>String</code> value
*/
public void debug( final String message )
{
debug( message, null );
}
/**
* Logs a debugging message and an exception.
*
* @param message a <code>String</code> value
* @param throwable a <code>Throwable</code> value
*/
public void debug( final String message, final Throwable throwable )
{
if ( m_logLevel <= LEVEL_DEBUG )
{
System.out.print( "[DEBUG] " );
System.out.println( message );
if ( null != throwable )
{
throwable.printStackTrace( System.out );
}
}
}
/**
* Returns <code>true</code> if debug-level logging is enabled, false
otherwise.
*
* @return <code>true</code> if debug-level logging
*/
public boolean isDebugEnabled()
{
return m_logLevel <= LEVEL_DEBUG;
}
/**
* Logs an informational message.
*
* @param message a <code>String</code> value
*/
public void info( final String message )
{
info( message, null );
}
/**
* Logs an informational message and an exception.
*
* @param message a <code>String</code> value
* @param throwable a <code>Throwable</code> value
*/
public void info( final String message, final Throwable throwable )
{
if ( m_logLevel <= LEVEL_INFO )
{
System.out.print( "[INFO] " );
System.out.println( message );
if ( null != throwable )
{
throwable.printStackTrace( System.out );
}
}
}
/**
* Returns <code>true</code> if info-level logging is enabled, false
otherwise.
*
* @return <code>true</code> if info-level logging is enabled
*/
public boolean isInfoEnabled()
{
return m_logLevel <= LEVEL_INFO;
}
/**
* Logs a warning message.
*
* @param message a <code>String</code> value
*/
public void warn( final String message )
{
warn( message, null );
}
/**
* Logs a warning message and an exception.
*
* @param message a <code>String</code> value
* @param throwable a <code>Throwable</code> value
*/
public void warn(final String message, final Throwable throwable)
{
if ( m_logLevel <= LEVEL_WARN )
{
System.out.print( "[WARNING] " );
System.out.println( message );
if ( null != throwable )
{
throwable.printStackTrace( System.out );
}
}
}
/**
* Returns <code>true</code> if warn-level logging is enabled, false
otherwise.
*
* @return <code>true</code> if warn-level logging is enabled
*/
public boolean isWarnEnabled()
{
return m_logLevel <= LEVEL_WARN;
}
/**
* Logs an error message.
*
* @param message a <code>String</code> value
*/
public void error( final String message )
{
error( message, null );
}
/**
* Logs an error message and an exception.
*
* @param message a <code>String</code> value
* @param throwable a <code>Throwable</code> value
*/
public void error( final String message, final Throwable throwable )
{
if ( m_logLevel <= LEVEL_ERROR )
{
System.out.print( "[ERROR] " );
System.out.println( message );
if ( null != throwable )
{
throwable.printStackTrace( System.out );
}
}
}
/**
* Returns <code>true</code> if error-level logging is enabled, false
otherwise.
*
* @return <code>true</code> if error-level logging is enabled
*/
public boolean isErrorEnabled()
{
return m_logLevel <= LEVEL_ERROR;
}
/**
* Logs a fatal error message.
*
* @param message a <code>String</code> value
*/
public void fatalError( final String message )
{
fatalError( message, null );
}
/**
* Logs a fatal error message and an exception.
*
* @param message a <code>String</code> value
* @param throwable a <code>Throwable</code> value
*/
public void fatalError( final String message, final Throwable throwable )
{
if ( m_logLevel <= LEVEL_FATAL )
{
System.out.print( "[FATAL ERROR] " );
System.out.println( message );
if ( null != throwable )
{
throwable.printStackTrace( System.out );
}
}
}
/**
* Returns <code>true</code> if fatal-level logging is enabled, false
otherwise.
*
* @return <code>true</code> if fatal-level logging is enabled
*/
public boolean isFatalErrorEnabled()
{
return m_logLevel <= LEVEL_FATAL;
}
/**
* Just returns this logger (<code>ConsoleLogger</code> is not
hierarchical).
*
* @param name ignored
* @return this logger
*/
public Logger getChildLogger( final String name )
{
return this;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/Jdk14Logger.java
Index: Jdk14Logger.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.framework.logger.impl;
import java.util.logging.Level;
import org.apache.framework.logger.Logger;
/**
* The default JDK 1.4 wrapper class for Logger. Please note that there is
* not an exact match to the priority levels that JDK 1.4 logging has and
* what LogKit or Log4J has. For that reason, the following priority level
* matching was used:
*
* <ul>
* <li>SEVERE = error, fatalError</li>
* <li>WARNING = warn</li>
* <li>INFO = info</li>
* <li>FINE = debug</li>
* </ul>
*
* <p>
* JDK 1.4 does allow you to have other levels like: CONFIG, FINER, and
* FINEST. Most projects don't separate out configuration logging from
* debugging information. Also, we wanted to maintain backwards
* compatibility as much as possible. Unfortunately, with all the
"fineness"
* details, there is no equivalent to the "error" log level.
* </p>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public final class Jdk14Logger
implements Logger
{
//The actual JDK1.4 logger implementation
private final java.util.logging.Logger m_logger;
/**
* Construct a Logger with specified jdk1.4 logger instance as
implementation.
*
* @param logImpl the jdk1.4 logger instance to delegate to
*/
public Jdk14Logger( java.util.logging.Logger logImpl )
{
m_logger = logImpl;
}
/**
* Log a debug message.
*
* @param message the message
*/
public final void debug( final String message )
{
m_logger.log( Level.FINE, message );
}
/**
* Log a debug message.
*
* @param message the message
* @param throwable the throwable
*/
public final void debug( final String message, final Throwable throwable )
{
m_logger.log( Level.FINE, message, throwable );
}
/**
* Determine if messages of priority "debug" will be logged.
*
* @return true if "debug" messages will be logged
*/
public final boolean isDebugEnabled()
{
return m_logger.isLoggable( Level.FINE );
}
/**
* Log a info message.
*
* @param message the message
*/
public final void info( final String message )
{
m_logger.log( Level.INFO, message );
}
/**
* Log a info message.
*
* @param message the message
* @param throwable the throwable
*/
public final void info( final String message, final Throwable throwable )
{
m_logger.log( Level.INFO, message, throwable );
}
/**
* Determine if messages of priority "info" will be logged.
*
* @return true if "info" messages will be logged
*/
public final boolean isInfoEnabled()
{
return m_logger.isLoggable( Level.INFO );
}
/**
* Log a warn message.
*
* @param message the message
*/
public final void warn( final String message )
{
m_logger.log( Level.WARNING, message );
}
/**
* Log a warn message.
*
* @param message the message
* @param throwable the throwable
*/
public final void warn( final String message, final Throwable throwable )
{
m_logger.log( Level.WARNING, message, throwable );
}
/**
* Determine if messages of priority "warn" will be logged.
*
* @return true if "warn" messages will be logged
*/
public final boolean isWarnEnabled()
{
return m_logger.isLoggable( Level.WARNING );
}
/**
* Log a error message.
*
* @param message the message
*/
public final void error( final String message )
{
m_logger.log( Level.SEVERE, message );
}
/**
* Log a error message.
*
* @param message the message
* @param throwable the throwable
*/
public final void error( final String message, final Throwable throwable )
{
m_logger.log( Level.SEVERE, message, throwable );
}
/**
* Determine if messages of priority "error" will be logged.
*
* @return true if "error" messages will be logged
*/
public final boolean isErrorEnabled()
{
return m_logger.isLoggable( Level.SEVERE );
}
/**
* Log a fatalError message.
*
* @param message the message
*/
public final void fatalError( final String message )
{
m_logger.log( Level.SEVERE, message );
}
/**
* Log a fatalError message.
*
* @param message the message
* @param throwable the throwable
*/
public final void fatalError( final String message, final Throwable
throwable )
{
m_logger.log( Level.SEVERE, message, throwable );
}
/**
* Determine if messages of priority "fatalError" will be logged.
*
* @return true if "fatalError" messages will be logged
*/
public final boolean isFatalErrorEnabled()
{
return m_logger.isLoggable( Level.SEVERE );
}
/**
* Create a new child logger.
* The name of the child logger is [current-loggers-name].[passed-in-name]
* Throws <code>IllegalArgumentException</code> if name has an empty
element name
*
* @param name the subname of this logger
* @return the new logger
*/
public final Logger getChildLogger( final String name )
{
return new Jdk14Logger( java.util.logging.Logger
.getLogger( m_logger.getName() + "." + name )
);
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/Log4JLogger.java
Index: Log4JLogger.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.framework.logger.impl;
import org.apache.log4j.Category;
import org.apache.log4j.Priority;
import org.apache.framework.logger.Logger;
/**
* The default Log4J wrapper class for Logger.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public final class Log4JLogger
implements Logger
{
//underlying implementation
private final Category m_logger;
/**
* Create a logger that delegates to specified category.
*
* @param logImpl the category to delegate to
*/
public Log4JLogger( final Category logImpl )
{
m_logger = logImpl;
}
/**
* Log a debug message.
*
* @param message the message
*/
public final void debug( final String message )
{
m_logger.debug(message);
}
/**
* Log a debug message.
*
* @param message the message
* @param throwable the throwable
*/
public final void debug( final String message, final Throwable throwable )
{
m_logger.debug( message, throwable );
}
/**
* Determine if messages of priority "debug" will be logged.
*
* @return true if "debug" messages will be logged
*/
public final boolean isDebugEnabled()
{
return m_logger.isDebugEnabled();
}
/**
* Log a info message.
*
* @param message the message
*/
public final void info( final String message )
{
m_logger.info( message );
}
/**
* Log a info message.
*
* @param message the message
* @param throwable the throwable
*/
public final void info( final String message, final Throwable throwable )
{
m_logger.info( message, throwable );
}
/**
* Determine if messages of priority "info" will be logged.
*
* @return true if "info" messages will be logged
*/
public final boolean isInfoEnabled()
{
return m_logger.isInfoEnabled();
}
/**
* Log a warn message.
*
* @param message the message
*/
public final void warn( final String message )
{
m_logger.warn( message );
}
/**
* Log a warn message.
*
* @param message the message
* @param throwable the throwable
*/
public final void warn( final String message, final Throwable throwable )
{
m_logger.warn( message, throwable );
}
/**
* Determine if messages of priority "warn" will be logged.
*
* @return true if "warn" messages will be logged
*/
public final boolean isWarnEnabled()
{
return m_logger.isEnabledFor( Priority.WARN );
}
/**
* Log a error message.
*
* @param message the message
*/
public final void error( final String message )
{
m_logger.error( message );
}
/**
* Log a error message.
*
* @param message the message
* @param throwable the throwable
*/
public final void error( final String message, final Throwable throwable )
{
m_logger.error( message, throwable );
}
/**
* Determine if messages of priority "error" will be logged.
*
* @return true if "error" messages will be logged
*/
public final boolean isErrorEnabled()
{
return m_logger.isEnabledFor( Priority.ERROR );
}
/**
* Log a fatalError message.
*
* @param message the message
*/
public final void fatalError( final String message )
{
m_logger.fatal( message );
}
/**
* Log a fatalError message.
*
* @param message the message
* @param throwable the throwable
*/
public final void fatalError( final String message, final Throwable
throwable )
{
m_logger.fatal( message, throwable );
}
/**
* Determine if messages of priority "fatalError" will be logged.
*
* @return true if "fatalError" messages will be logged
*/
public final boolean isFatalErrorEnabled()
{
return m_logger.isEnabledFor( Priority.FATAL );
}
/**
* Create a new child logger.
* The name of the child logger is [current-loggers-name].[passed-in-name]
* Throws <code>IllegalArgumentException</code> if name has an empty
element name
*
* @param name the subname of this logger
* @return the new logger
*/
public final Logger getChildLogger( final String name )
{
return new Log4JLogger( Category.getInstance( m_logger.getName() +
"." + name ) );
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/LogKitLogger.java
Index: LogKitLogger.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.framework.logger.impl;
import org.apache.framework.logger.Logger;
/**
* The default LogKit wrapper class for Logger.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public final class LogKitLogger
implements Logger
{
//underlying implementation to delegate to
private final org.apache.log.Logger m_logger;
/**
* Create a logger that delegates to specified logger.
*
* @param logImpl the LogKit logger to delegate to
*/
public LogKitLogger( org.apache.log.Logger logImpl )
{
m_logger = logImpl;
}
/**
* Log a debug message.
*
* @param message the message
*/
public final void debug( final String message )
{
m_logger.debug(message);
}
/**
* Log a debug message.
*
* @param message the message
* @param throwable the throwable
*/
public final void debug( final String message, final Throwable throwable )
{
m_logger.debug( message, throwable );
}
/**
* Determine if messages of priority "debug" will be logged.
*
* @return true if "debug" messages will be logged
*/
public final boolean isDebugEnabled()
{
return m_logger.isDebugEnabled();
}
/**
* Log a info message.
*
* @param message the message
*/
public final void info( final String message )
{
m_logger.info( message );
}
/**
* Log a info message.
*
* @param message the message
* @param throwable the throwable
*/
public final void info( final String message, final Throwable throwable )
{
m_logger.info( message, throwable );
}
/**
* Determine if messages of priority "info" will be logged.
*
* @return true if "info" messages will be logged
*/
public final boolean isInfoEnabled()
{
return m_logger.isInfoEnabled();
}
/**
* Log a warn message.
*
* @param message the message
*/
public final void warn( final String message )
{
m_logger.warn( message );
}
/**
* Log a warn message.
*
* @param message the message
* @param throwable the throwable
*/
public final void warn( final String message, final Throwable throwable )
{
m_logger.warn( message, throwable );
}
/**
* Determine if messages of priority "warn" will be logged.
*
* @return true if "warn" messages will be logged
*/
public final boolean isWarnEnabled()
{
return m_logger.isWarnEnabled();
}
/**
* Log a error message.
*
* @param message the message
*/
public final void error( final String message )
{
m_logger.error( message );
}
/**
* Log a error message.
*
* @param message the message
* @param throwable the throwable
*/
public final void error( final String message, final Throwable throwable )
{
m_logger.error( message, throwable );
}
/**
* Determine if messages of priority "error" will be logged.
*
* @return true if "error" messages will be logged
*/
public final boolean isErrorEnabled()
{
return m_logger.isErrorEnabled();
}
/**
* Log a fatalError message.
*
* @param message the message
*/
public final void fatalError( final String message )
{
m_logger.fatalError( message );
}
/**
* Log a fatalError message.
*
* @param message the message
* @param throwable the throwable
*/
public final void fatalError( final String message, final Throwable
throwable )
{
m_logger.fatalError( message, throwable );
}
/**
* Determine if messages of priority "fatalError" will be logged.
*
* @return true if "fatalError" messages will be logged
*/
public final boolean isFatalErrorEnabled()
{
return m_logger.isFatalErrorEnabled();
}
/**
* Create a new child logger.
* The name of the child logger is [current-loggers-name].[passed-in-name]
* Throws <code>IllegalArgumentException</code> if name has an empty
element name
*
* @param name the subname of this logger
* @return the new logger
*/
public final Logger getChildLogger( final String name )
{
return new LogKitLogger( m_logger.getChildLogger( name ) );
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/logger/impl/NullLogger.java
Index: NullLogger.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.framework.logger.impl;
import org.apache.framework.logger.Logger;
/**
* The Null Logger class. This is useful for implementations where you need
* to provide a logger to a utility class, but do not want any output from it.
* It also helps when you have a utility that does not have a logger to
supply.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @version 1.0
*/
public final class NullLogger implements Logger
{
/**
* Creates a new <code>NullLogger</code>.
*/
public NullLogger()
{
}
/**
* No-op.
*
* @param message ignored
*/
public void debug(String message)
{
}
/**
* No-op.
*
* @param message ignored
* @param throwable ignored
*/
public void debug(String message, Throwable throwable)
{
}
/**
* No-op.
*
* @return <code>false</code>
*/
public boolean isDebugEnabled()
{
return false;
}
/**
* No-op.
*
* @param message ignored
*/
public void info(String message)
{
}
/**
* No-op.
*
* @param message ignored
* @param throwable ignored
*/
public void info(String message, Throwable throwable)
{
}
/**
* No-op.
*
* @return <code>false</code>
*/
public boolean isInfoEnabled()
{
return false;
}
/**
* No-op.
*
* @param message ignored
*/
public void warn(String message)
{
}
/**
* No-op.
*
* @param message ignored
* @param throwable ignored
*/
public void warn(String message, Throwable throwable)
{
}
/**
* No-op.
*
* @return <code>false</code>
*/
public boolean isWarnEnabled()
{
return false;
}
/**
* No-op.
*
* @param message ignored
*/
public void error(String message)
{
}
/**
* No-op.
*
* @param message ignored
* @param throwable ignored
*/
public void error(String message, Throwable throwable)
{
}
/**
* No-op.
*
* @return <code>false</code>
*/
public boolean isErrorEnabled()
{
return false;
}
/**
* No-op.
*
* @param message ignored
*/
public void fatalError(String message)
{
}
/**
* No-op.
*
* @param message ignored
* @param throwable ignored
*/
public void fatalError(String message, Throwable throwable)
{
}
/**
* No-op.
*
* @return <code>false</code>
*/
public boolean isFatalErrorEnabled()
{
return false;
}
/**
* Returns this <code>NullLogger</code>.
*
* @param name ignored
* @return this <code>NullLogger</code>
*/
public Logger getChildLogger(String name)
{
return this;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/ParameterException.java
Index: ParameterException.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.framework.parameters;
/**
* Thrown when a <code>Parameterizable</code> component cannot be
parameterized
* properly, or if a value cannot be retrieved properly.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public final class ParameterException
extends Exception
{
/**
* The Throwable that caused this exception to be thrown.
*/
private final Throwable m_throwable;
/**
* Construct a new <code>ParameterException</code> instance.
*
* @param message The detail message for this exception.
*/
public ParameterException( final String message )
{
this( message, null );
}
/**
* Construct a new <code>ParameterException</code> instance.
*
* @param message The detail message for this exception.
* @param throwable the root cause of the exception
*/
public ParameterException( final String message, final Throwable
throwable )
{
super( message );
m_throwable = throwable;
}
/**
* Retrieve root cause of the exception.
*
* @return the root cause
*/
public final Throwable getCause()
{
return m_throwable;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/Parameterizable.java
Index: Parameterizable.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.framework.parameters;
/**
* Components should implement this interface if they wish to
* be provided with parameters during startup.
* <p>
* The Parameterizable interface is a light-weight alternative to the
* [EMAIL PROTECTED] org.apache.framework.configuration.Configurable}
* interface. As such, the <code>Parameterizable</code> interface and
* the <code>Configurable</code> interface are <strong>not</strong>
* compatible.
* </p><p>
* This interface will be called after
* <code>Composable.compose()</code> and before
* <code>Initializable.initialize()</code>.
* </p>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
*/
public interface Parameterizable
{
/**
* Provide component with parameters.
*
* @param parameters the parameters
* @exception ParameterException if parameters are invalid
*/
void parameterize( Parameters parameters )
throws ParameterException;
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/Parameters.java
Index: Parameters.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.framework.parameters;
import java.io.Serializable;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.Properties;
import org.apache.framework.configuration.Configuration;
import org.apache.framework.configuration.ConfigurationException;
/**
* The <code>Parameters</code> class represents a set of key-value
* pairs.
* <p>
* The <code>Parameters</code> object provides a mechanism to obtain
* values based on a <code>String</code> name. There are convenience
* methods that allow you to use defaults if the value does not exist,
* as well as obtain the value in any of the same formats that are in
* the [EMAIL PROTECTED] Configuration} interface.
* </p><p>
* While there are similarities between the <code>Parameters</code>
* object and the java.util.Properties object, there are some
* important semantic differences. First, <code>Parameters</code> are
* <i>read-only</i>. Second, <code>Parameters</code> are easily
* derived from [EMAIL PROTECTED] Configuration} objects. Lastly, the
* <code>Parameters</code> object is derived from XML fragments that
* look like this:
* <pre><code>
* <parameter name="param-name" value="param-value" />
* </code></pre>
* </p><p>
* <strong>Note: this class is not thread safe by default.</strong> If you
* require thread safety please synchronize write access to this class to
* prevent potential data corruption.
* </p>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @version 1.0
*/
public class Parameters
implements Serializable
{
/** Empty Parameters object */
public static final Parameters EMPTY_PARAMETERS;
/** Static initializer to initialize the empty Parameters object */
static
{
EMPTY_PARAMETERS = new Parameters();
EMPTY_PARAMETERS.makeReadOnly();
}
///Underlying store of parameters
private Map m_parameters = new HashMap();
private boolean m_readOnly;
/**
* Set the <code>String</code> value of a specified parameter.
* <p />
* If the specified value is <b>null</b> the parameter is removed.
*
* @param name a <code>String</code> value
* @param value a <code>String</code> value
* @return The previous value of the parameter or <b>null</b>.
* @exception IllegalStateException if the Parameters object is read-only
*/
public String setParameter( final String name, final String value )
throws IllegalStateException
{
checkWriteable();
if( null == name )
{
return null;
}
if( null == value )
{
return (String)m_parameters.remove( name );
}
return (String)m_parameters.put( name, value );
}
/**
* Remove a parameter from the parameters object
* @param name a <code>String</code> value
*/
public void removeParameter( final String name )
{
setParameter( name, null );
}
/**
* Return an <code>Iterator</code> view of all parameter names.
*
* @return a iterator of parameter names
* @deprecated Use getNames() instead
*/
public Iterator getParameterNames()
{
return m_parameters.keySet().iterator();
}
/**
* Retrieve an array of all parameter names.
*
* @return the parameters names
*/
public String[] getNames()
{
return (String[])m_parameters.keySet().toArray( new String[ 0 ] );
}
/**
* Test if the specified parameter can be retrieved.
*
* @param name the parameter name
* @return true if parameter is a name
*/
public boolean isParameter( final String name )
{
return m_parameters.containsKey( name );
}
/**
* Retrieve the <code>String</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, an exception is thrown.
*
* @param name the name of parameter
* @return the value of parameter
* @throws ParameterException if the specified parameter cannot be found
*/
public String getParameter( final String name )
throws ParameterException
{
if( null == name )
{
throw new ParameterException( "You cannot lookup a null
parameter" );
}
final String test = (String)m_parameters.get( name );
if( null == test )
{
throw new ParameterException( "The parameter '" + name +
"' does not contain a value" );
}
return test;
}
/**
* Retrieve the <code>String</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, <code>defaultValue</code>
* is returned.
*
* @param name the name of parameter
* @param defaultValue the default value, returned if parameter does not
exist
* @return the value of parameter
*/
public String getParameter( final String name, final String defaultValue )
{
try
{
return getParameter( name );
}
catch( final ParameterException pe )
{
return defaultValue;
}
}
/**
* Retrieve the <code>int</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, an exception is thrown.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of parameter
* @return the integer parameter type
* @throws ParameterException if the specified parameter cannot be found
*/
public int getParameterAsInteger( final String name )
throws ParameterException
{
try
{
final String value = getParameter( name );
if( value.startsWith( "0x" ) )
{
return Integer.parseInt( value.substring(2), 16 );
}
else if( value.startsWith( "0o" ) )
{
return Integer.parseInt( value.substring(2), 8 );
}
else if( value.startsWith( "0b" ) )
{
return Integer.parseInt( value.substring(2), 2 );
}
else
{
return Integer.parseInt( value );
}
}
catch( final Exception e )
{
throw new ParameterException( "Could not return an integer
value", e );
}
}
/**
* Retrieve the <code>int</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, <code>defaultValue</code>
* is returned.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of parameter
* @param defaultValue value returned if parameter does not exist or is
of wrong type
* @return the integer parameter type
*/
public int getParameterAsInteger( final String name, final int
defaultValue )
{
try
{
return getParameterAsInteger( name );
}
catch( final ParameterException pe )
{
return defaultValue;
}
}
/**
* Retrieve the <code>long</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, an exception is thrown.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of parameter
* @return the long parameter type
* @throws ParameterException if the specified parameter cannot be found
*/
public long getParameterAsLong( final String name )
throws ParameterException
{
try
{
final String value = getParameter( name );
if( value.startsWith( "0x" ) )
{
return Long.parseLong( value.substring(2), 16 );
}
else if( value.startsWith( "0o" ) )
{
return Long.parseLong( value.substring(2), 8 );
}
else if( value.startsWith( "0b" ) )
{
return Long.parseLong( value.substring(2), 2 );
}
else
{
return Long.parseLong( value );
}
}
catch( final Exception e )
{
throw new ParameterException( "Could not return a long value", e
);
}
}
/**
* Retrieve the <code>long</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, <code>defaultValue</code>
* is returned.
*
* Hexadecimal numbers begin with 0x, Octal numbers begin with 0o and
binary
* numbers begin with 0b, all other values are assumed to be decimal.
*
* @param name the name of parameter
* @param defaultValue value returned if parameter does not exist or is
of wrong type
* @return the long parameter type
*/
public long getParameterAsLong( final String name, final long
defaultValue )
{
try
{
return getParameterAsLong( name );
}
catch( final ParameterException pe )
{
return defaultValue;
}
}
/**
* Retrieve the <code>float</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, an exception is thrown.
*
* @param name the parameter name
* @return the value
* @throws ParameterException if the specified parameter cannot be found
*/
public float getParameterAsFloat( final String name )
throws ParameterException
{
try
{
return Float.parseFloat( getParameter( name ) );
}
catch( final Exception e )
{
throw new ParameterException( "Could not return a float value", e
);
}
}
/**
* Retrieve the <code>float</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, <code>defaultValue</code>
* is returned.
*
* @param name the parameter name
* @param defaultValue the default value if parameter does not exist or
is of wrong type
* @return the value
*/
public float getParameterAsFloat( final String name, final float
defaultValue )
{
try
{
return getParameterAsFloat( name );
}
catch( final ParameterException pe )
{
return defaultValue;
}
}
/**
* Retrieve the <code>boolean</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, an exception is thrown.
*
* @param name the parameter name
* @return the value
* @exception ParameterException if an error occurs
* @exception ParemterException
*/
public boolean getParameterAsBoolean( final String name )
throws ParameterException
{
final String value = getParameter( name );
if( value.equalsIgnoreCase( "true" ) )
{
return true;
}
else if( value.equalsIgnoreCase( "false" ) )
{
return false;
}
else
{
throw new ParameterException( "Could not return a boolean value"
);
}
}
/**
* Retrieve the <code>boolean</code> value of the specified parameter.
* <p />
* If the specified parameter cannot be found, <code>defaultValue</code>
* is returned.
*
* @param name the parameter name
* @param defaultValue the default value if parameter does not exist or
is of wrong type
* @return the value
*/
public boolean getParameterAsBoolean( final String name, final boolean
defaultValue )
{
try
{
return getParameterAsBoolean( name );
}
catch( final ParameterException e )
{
return defaultValue;
}
}
/**
* Merge parameters from another <code>Parameters</code> instance
* into this.
*
* @param other the other Parameters
* @return This <code>Parameters</code> instance.
*/
public Parameters merge( final Parameters other )
{
checkWriteable();
final Iterator names = other.getParameterNames();
while( names.hasNext() )
{
final String name = (String) names.next();
String value = null;
try
{
value = other.getParameter( name );
}
catch( final ParameterException pe )
{
value = null;
}
setParameter( name, value );
}
return this;
}
/**
* Make this Parameters read-only so that it will throw a
* <code>IllegalStateException</code> if someone tries to
* modify it.
*/
public void makeReadOnly()
{
m_readOnly = true;
}
/**
* Checks is this <code>Parameters</code> object is writeable.
*
* @exception IllegalStateException if this <code>Parameters</code>
object is read-only
*/
protected final void checkWriteable()
throws IllegalStateException
{
if( m_readOnly )
{
throw new IllegalStateException( "Context is read only and can
not be modified" );
}
}
/**
* Create a <code>Parameters</code> object from a
<code>Configuration</code>
* object. This acts exactly like the following method call:
* <pre>
* Parameters.fromConfiguration(configuration, "parameter");
* </pre>
*
* @param configuration the Configuration
* @return This <code>Parameters</code> instance.
* @exception ConfigurationException if an error occurs
*/
public static Parameters fromConfiguration( final Configuration
configuration )
throws ConfigurationException
{
return fromConfiguration( configuration, "parameter" );
}
/**
* Create a <code>Parameters</code> object from a
<code>Configuration</code>
* object using the supplied element name.
*
* @param configuration the Configuration
* @param elementName the element name for the parameters
* @return This <code>Parameters</code> instance.
* @exception ConfigurationException if an error occurs
*/
public static Parameters fromConfiguration( final Configuration
configuration,
final String elementName )
throws ConfigurationException
{
if( null == configuration )
{
throw new ConfigurationException( "You cannot convert to
parameters with " +
"a null Configuration" );
}
final Configuration[] parameters = configuration.getChildren(
elementName );
final Parameters params = new Parameters();
for( int i = 0; i < parameters.length; i++ )
{
try
{
final String name = parameters[ i ].getAttribute( "name" );
final String value = parameters[ i ].getAttribute( "value" );
params.setParameter( name, value );
}
catch( final Exception e )
{
throw new ConfigurationException( "Cannot process
Configurable", e );
}
}
return params;
}
/**
* Create a <code>Parameters</code> object from a <code>Properties</code>
* object.
*
* @param properties the Properties
* @return This <code>Parameters</code> instance.
*/
public static Parameters fromProperties( final Properties properties )
{
final Parameters parameters = new Parameters();
final Enumeration names = properties.propertyNames();
while( names.hasMoreElements() )
{
final String key = (String)names.nextElement().toString();
final String value = properties.getProperty( key );
parameters.setParameter( key, value );
}
return parameters;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/parameters/package.html
Index: package.html
===================================================================
<body>
Interfaces supporting the supply of flat configuration information.
</body>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/ServiceException.java
Index: ServiceException.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.framework.service;
/**
* The exception thrown to indicate a problem with service.
* It is usually thrown by ServiceManager or ServiceSelector.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stephen McConnell</a>
*/
public class ServiceException
extends Exception
{
/**
* The Throwable that caused this exception to be thrown.
*/
private final Throwable m_throwable;
/**
* Construct a new <code>ServiceException</code> instance.
*
* @param message the exception message
*/
public ServiceException( final String message )
{
this( message, null );
}
/**
* Construct a new <code>ServiceException</code> instance.
*
* @param message the exception message
* @param throwable the throwable
*/
public ServiceException( final String message, final Throwable throwable )
{
super( message );
m_throwable = throwable;
}
/**
* Retrieve root cause of the exception.
*
* @return the root cause
*/
public final Throwable getCause()
{
return m_throwable;
}
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/ServiceManager.java
Index: ServiceManager.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.framework.service;
/**
* A <code>ServiceManager</code> selects <code>Object</code>s based on a
* role. The contract is that all the <code>Object</code>s implement the
* differing roles and there is one <code>Object</code> per role. If you
* need to select on of many <code>Object</code>s that implement the same
* role, then you need to use a <code>ServiceSelector</code>. Roles are
* usually the full interface name.
*
* A role is better understood by the analogy of a play. There are many
* different roles in a script. Any actor or actress can play any given part
* and you get the same results (phrases said, movements made, etc.). The
exact
* nuances of the performance is different.
*
* Below is a list of things that might be considered the different roles:
*
* <ul>
* <li> InputAdaptor and OutputAdaptor</li>
* <li> Store and Spool</li>
* </ul>
*
* The <code>ServiceManager</code> does not specify the methodology of
* getting the <code>Object</code>, merely the interface used to get it.
* Therefore the <code>ServiceManager</code> can be implemented with a
* factory pattern, an object pool, or a simple Hashtable.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stephen McConnell</a>
* @version 1.0
* @see org.apache.framework.service.Serviceable
*/
public interface ServiceManager
{
/**
* Get the <code>Object</code> associated with the given role. For
* instance, If the <code>ServiceManager</code> had a
* <code>LoggerComponent</code> stored and referenced by role, I would use
* the following call:
* <pre>
* try
* {
* MyComponent log;
* myComponent = (MyComponent) manager.lookup(MyComponent.ROLE);
* }
* catch (...)
* {
* ...
* }
* </pre>
*
* @param role The role name of the <code>Object</code> to retrieve.
* @return an <code>Object</code> value
* @exception ServiceException if an error occurs
*/
Object lookup( String role )
throws ServiceException;
/**
* Check to see if a <code>Object</code> exists for a role.
*
* @param role a string identifying the role to check.
* @return True if the object exists, False if it does not.
*/
boolean hasService( String role );
/**
* Return the <code>Object</code> when you are finished with it. This
* allows the <code>ServiceManager</code> to handle the End-Of-Life
Lifecycle
* events associated with the <code>Object</code>. Please note, that no
* Exception should be thrown at this point. This is to allow easy use
of the
* ServiceManager system without having to trap Exceptions on a release.
*
* @param object The <code>Object</code> we are releasing.
*/
void release( Object object );
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/Serviceable.java
Index: Serviceable.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.framework.service;
/**
* A Serviceable is a class that need to connect to software components using
* a "role" abstraction, thus not depending on particular implementations
* but on behavioral interfaces.
* <br />
*
* The contract surrounding a <code>Serviceable</code> is that it is a user.
* The <code>Serviceable</code> is able to use <code>Object</code>s managed
* by the <code>ServiceManager</code> it was initialized with. As part
* of the contract with the system, the instantiating entity must call
* the <code>compose</code> method before the <code>Serviceable</code>
* can be considered valid.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stephen McConnell</a>
* @version 1.0
* @see org.apache.framework.service.ServiceManager
*
*/
public interface Serviceable
{
/**
* Pass the <code>ServiceManager</code> to the <code>Serviceable</code>.
* The <code>Serviceable</code> implementation should use the specified
* <code>ServiceManager</code> to acquire the components it needs for
* execution.
*
* @param manager The <code>ServiceManager</code> which this
* <code>Serviceable</code> uses.
* @exception ServiceException if an error occurs
*/
void service( ServiceManager manager )
throws ServiceException;
}
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/package.html
Index: package.html
===================================================================
<body>
Interfaces and default implementation of a service management framework
supporting container based service lookup and decommissioning.
</body>
1.1
jakarta-avalon/src/proposal/avalon5/org/apache/framework/service/impl/DefaultServiceManager.java
Index: DefaultServiceManager.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.framework.service.impl;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import org.apache.framework.service.ServiceManager;
import org.apache.framework.service.ServiceException;
/**
* This class is a static implementation of a ServiceManager. Allow ineritance
* and extension so you can generate a tree of ServiceManager each defining
* Object scope.
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Stephen McConnell</a>
* @version 1.0
*/
public class DefaultServiceManager
implements ServiceManager
{
private final HashMap m_objects = new HashMap();
private final ServiceManager m_parent;
private boolean m_readOnly;
/**
* Construct ServiceManager with no parent.
*
*/
public DefaultServiceManager()
{
this( null );
}
/**
* Construct ServiceManager with specified parent.
*
* @param parent the ServiceManager parent
*/
public DefaultServiceManager( final ServiceManager parent )
{
m_parent = parent;
}
/**
* Retrieve Object by role from ServiceManager.
*
* @param role the role
* @return the Object
* @exception org.apache.framework.service.ServiceException if an error
occurs
*/
public Object lookup( final String role )
throws ServiceException
{
final Object object = m_objects.get( role );
if( null != object )
{
return object;
}
else if( null != m_parent )
{
return m_parent.lookup( role );
}
else
{
throw new ServiceException( "Unable to provide implementation for
" + role );
}
}
/**
* Check to see if a <code>Object</code> exists for a role.
*
* @param role a string identifying the role to check.
* @return True if the object exists, False if it does not.
*/
public boolean hasService( final String role )
{
boolean objectExists = false;
try
{
this.lookup(role);
objectExists = true;
}
catch (Throwable t)
{
// Ignore all throwables--we want a yes or no answer.
}
return objectExists;
}
/**
* Place Object into ComponentManager.
*
* @param role the components role
* @param object an <code>Object</code> value
*/
public void put( final String role, final Object object )
{
checkWriteable();
m_objects.put( role, object );
}
/**
* Build a human readable representation of the ServiceManager.
*
* @return the description of the ServiceManager
*/
public String toString()
{
final StringBuffer buffer = new StringBuffer();
final Iterator objects = m_objects.keySet().iterator();
buffer.append( "Services:" );
while( objects.hasNext() )
{
buffer.append( "[" );
buffer.append( objects.next() );
buffer.append( "]" );
}
return buffer.toString();
}
/**
* Helper method for subclasses to retrieve parent.
*
* @return the parent ServiceManager
*/
protected final ServiceManager getParent()
{
return m_parent;
}
/**
* Helper method for subclasses to retrieve object map.
*
* @return the object map
*/
protected final Map getObjectMap()
{
return m_objects;
}
/**
* Makes this service manager read-only.
*
*/
public void makeReadOnly()
{
m_readOnly = true;
}
/**
* Checks if this service manager is writeable.
*
* @exception java.lang.IllegalStateException if this service manager is
read-only
*/
protected final void checkWriteable()
throws IllegalStateException
{
if( m_readOnly )
{
throw new IllegalStateException
( "ServiceManager is read only and can not be modified" );
}
}
/**
* Release the object.
* @param object The <code>Object</code> to release.
*/
public void release( Object object ){}
}
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
