/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.avalon.framework;
import java.util.Map;
Basic enum class for type-safe enums with values. Valued enum items can be compared and ordered
with the provided methods. Should be used as an abstract base. For example:
import org.apache.avalon.framework.ValuedEnum;
public final class JavaVersion
extends ValuedEnum
{
//standard enums for version of JVM
public static final JavaVersion JAVA1_0 = new JavaVersion( "Java 1.0", 100 );
public static final JavaVersion JAVA1_1 = new JavaVersion( "Java 1.1", 110 );
public static final JavaVersion JAVA1_2 = new JavaVersion( "Java 1.2", 120 );
public static final JavaVersion JAVA1_3 = new JavaVersion( "Java 1.3", 130 );
private JavaVersion( final String name, final int value )
{
super( name, value );
}
}
The above class could then be used as follows:
import org.apache.avalon.framework.context.Context;
import org.apache.avalon.framework.context.Contextualizable;
import org.apache.avalon.framework.context.ContextException;
public class MyComponent implements Contextualizable
{
JavaVersion requiredVer = JavaVersion.JAVA1_2;
public void contextualize(Context context)
throws ContextException
{
JavaVersion ver = (JavaVersion)context.get("java.version");
if ( ver.isLessThan( requiredVer ) )
{
throw new RuntimeException( requiredVer.getName()+" or higher required" );
}
}
}
As with Enum
, the ValuedEnum(String, int, Map)
constructor can be used to populate a Map
, from which further functionality can be derived.
NOTE: between 4.0 and 4.1, the constructors' access has been changed
from public
to protected
. This is to prevent users
of the Enum breaking type-safety by defining new Enum items. All Enum items
should be defined in the Enum class, as shown above.
Author: Avalon Development Team Version: $Id: ValuedEnum.java 506231 2007-02-12 02:36:54Z crossley $
/**
* Basic enum class for type-safe enums with values. Valued enum items can be compared and ordered
* with the provided methods. Should be used as an abstract base. For example:
*
* <pre>
* import org.apache.avalon.framework.ValuedEnum;
*
* public final class JavaVersion
* extends ValuedEnum
* {
* //standard enums for version of JVM
* public static final JavaVersion JAVA1_0 = new JavaVersion( "Java 1.0", 100 );
* public static final JavaVersion JAVA1_1 = new JavaVersion( "Java 1.1", 110 );
* public static final JavaVersion JAVA1_2 = new JavaVersion( "Java 1.2", 120 );
* public static final JavaVersion JAVA1_3 = new JavaVersion( "Java 1.3", 130 );
*
* private JavaVersion( final String name, final int value )
* {
* super( name, value );
* }
* }
* </pre>
*
* The above class could then be used as follows:
* <pre>
* import org.apache.avalon.framework.context.Context;
* import org.apache.avalon.framework.context.Contextualizable;
* import org.apache.avalon.framework.context.ContextException;
*
* public class MyComponent implements Contextualizable
* {
* JavaVersion requiredVer = JavaVersion.JAVA1_2;
*
* public void contextualize(Context context)
* throws ContextException
* {
* JavaVersion ver = (JavaVersion)context.get("java.version");
* if ( ver.isLessThan( requiredVer ) )
* {
* throw new RuntimeException( requiredVer.getName()+" or higher required" );
* }
* }
* }
* </pre>
*
* As with <code>Enum</code>, the {@link #ValuedEnum(String, int, Map)} constructor can be used to
* populate a <code>Map</code>, from which further functionality can be derived.
*
* <p>
* <em>NOTE:</em> between 4.0 and 4.1, the constructors' access has been changed
* from <code>public</code> to <code>protected</code>. This is to prevent users
* of the Enum breaking type-safety by defining new Enum items. All Enum items
* should be defined in the Enum class, as shown above.
* </p>
*
* @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
* @version $Id: ValuedEnum.java 506231 2007-02-12 02:36:54Z crossley $
*/
public abstract class ValuedEnum
extends Enum
{
The value contained in enum.
/**
* The value contained in enum.
*/
private final int m_value;
Constructor for enum item.
Note: access changed from public
to
protected
after 4.0. See class description.
Params: - name – the name of enum item.
- value – the value of enum item.
/**
* Constructor for enum item.
*
* <p>
* <em>Note:</em> access changed from <code>public</code> to
* <code>protected</code> after 4.0. See class description.
* </p>
*
*
* @param name the name of enum item.
* @param value the value of enum item.
*/
protected ValuedEnum( final String name, final int value )
{
this( name, value, null );
}
Constructor for enum item so that it gets added to Map at creation.
Adding to a map is useful for implementing find...() style methods.
Note: access changed from public
to
protected
after 4.0. See class description.
Params: - name – the name of enum item.
- value – the value of enum item.
- map – the
Map
to add enum item to.
/**
* Constructor for enum item so that it gets added to Map at creation.
* Adding to a map is useful for implementing find...() style methods.
*
* </p>
* <em>Note:</em> access changed from <code>public</code> to
* <code>protected</code> after 4.0. See class description.
* </p>
*
* @param name the name of enum item.
* @param value the value of enum item.
* @param map the <code>Map</code> to add enum item to.
*/
protected ValuedEnum( final String name, final int value, final Map map )
{
super( name, map );
m_value = value;
}
Get value of enum item.
Returns: the enum item's value.
/**
* Get value of enum item.
*
* @return the enum item's value.
*/
public final int getValue()
{
return m_value;
}
Test if enum item is equal in value to other enum.
Params: - other – the other enum
Returns: true if equal
/**
* Test if enum item is equal in value to other enum.
*
* @param other the other enum
* @return true if equal
*/
public final boolean isEqualTo( final ValuedEnum other )
{
return m_value == other.m_value;
}
Test if enum item is greater than in value to other enum.
Params: - other – the other enum
Returns: true if greater than
/**
* Test if enum item is greater than in value to other enum.
*
* @param other the other enum
* @return true if greater than
*/
public final boolean isGreaterThan( final ValuedEnum other )
{
return m_value > other.m_value;
}
Test if enum item is greater than or equal in value to other enum.
Params: - other – the other enum
Returns: true if greater than or equal
/**
* Test if enum item is greater than or equal in value to other enum.
*
* @param other the other enum
* @return true if greater than or equal
*/
public final boolean isGreaterThanOrEqual( final ValuedEnum other )
{
return m_value >= other.m_value;
}
Test if enum item is less than in value to other enum.
Params: - other – the other enum
Returns: true if less than
/**
* Test if enum item is less than in value to other enum.
*
* @param other the other enum
* @return true if less than
*/
public final boolean isLessThan( final ValuedEnum other )
{
return m_value < other.m_value;
}
Test if enum item is less than or equal in value to other enum.
Params: - other – the other enum
Returns: true if less than or equal
/**
* Test if enum item is less than or equal in value to other enum.
*
* @param other the other enum
* @return true if less than or equal
*/
public final boolean isLessThanOrEqual( final ValuedEnum other )
{
return m_value <= other.m_value;
}
Tests for equality. Two Enum:s are considered equal
if they are of the same class, have the same name, and same value.
Params: - o – the other object
Returns: the equality status
/**
* Tests for equality. Two Enum:s are considered equal
* if they are of the same class, have the same name, and same value.
*
* @param o the other object
* @return the equality status
*/
public boolean equals( Object o )
{
boolean prelim = super.equals( o );
if( ! prelim )
return false;
if( !(o instanceof ValuedEnum) )
return false;
final ValuedEnum enumerated = (ValuedEnum) o;
return m_value == enumerated.m_value;
}
public int hashCode()
{
int hash = super.hashCode();
hash ^= m_value;
hash >>>= (m_value & 31 );
return hash;
}
Override toString method to produce human readable description.
Returns: String in the form type[name=value]
, eg.:
JavaVersion[Java 1.0=100]
.
/**
* Override toString method to produce human readable description.
*
* @return String in the form <code>type[name=value]</code>, eg.:
* <code>JavaVersion[Java 1.0=100]</code>.
*/
public String toString()
{
return getClass().getName() + "[" + getName() + "=" + m_value + "]";
}
}