You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by tr...@apache.org on 2006/01/20 14:48:55 UTC
svn commit: r370807 [16/22] - in /directory/sandbox/trustin/mina-spi: ./
core/src/main/java/org/apache/mina/common/
core/src/main/java/org/apache/mina/common/support/
core/src/main/java/org/apache/mina/common/support/discovery/
core/src/main/java/org/a...
Added: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/Enum.java
URL: http://svn.apache.org/viewcvs/directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/Enum.java?rev=370807&view=auto
==============================================================================
--- directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/Enum.java (added)
+++ directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/Enum.java Fri Jan 20 05:47:50 2006
@@ -0,0 +1,604 @@
+/*
+ * Copyright 2002-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.mina.common.support.lang.enums;
+
+import java.io.Serializable;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.mina.common.support.lang.ClassUtils;
+import org.apache.mina.common.support.lang.StringUtils;
+
+/**
+ * <p>Abstract superclass for type-safe enums.</p>
+ *
+ * <p>One feature of the C programming language lacking in Java is enumerations. The
+ * C implementation based on ints was poor and open to abuse. The original Java
+ * recommendation and most of the JDK also uses int constants. It has been recognised
+ * however that a more robust type-safe class-based solution can be designed. This
+ * class follows the basic Java type-safe enumeration pattern.</p>
+ *
+ * <p><em>NOTE:</em> Due to the way in which Java ClassLoaders work, comparing
+ * Enum objects should always be done using <code>equals()</code>, not <code>==</code>.
+ * The equals() method will try == first so in most cases the effect is the same.</p>
+ *
+ * <p>Of course, if you actually want (or don't mind) Enums in different class
+ * loaders being non-equal, then you can use <code>==</code>.</p>
+ *
+ * <h4>Simple Enums</h4>
+ *
+ * <p>To use this class, it must be subclassed. For example:</p>
+ *
+ * <pre>
+ * public final class ColorEnum extends Enum {
+ * public static final ColorEnum RED = new ColorEnum("Red");
+ * public static final ColorEnum GREEN = new ColorEnum("Green");
+ * public static final ColorEnum BLUE = new ColorEnum("Blue");
+ *
+ * private ColorEnum(String color) {
+ * super(color);
+ * }
+ *
+ * public static ColorEnum getEnum(String color) {
+ * return (ColorEnum) getEnum(ColorEnum.class, color);
+ * }
+ *
+ * public static Map getEnumMap() {
+ * return getEnumMap(ColorEnum.class);
+ * }
+ *
+ * public static List getEnumList() {
+ * return getEnumList(ColorEnum.class);
+ * }
+ *
+ * public static Iterator iterator() {
+ * return iterator(ColorEnum.class);
+ * }
+ * }
+ * </pre>
+ *
+ * <p>As shown, each enum has a name. This can be accessed using <code>getName</code>.</p>
+ *
+ * <p>The <code>getEnum</code> and <code>iterator</code> methods are recommended.
+ * Unfortunately, Java restrictions require these to be coded as shown in each subclass.
+ * An alternative choice is to use the {@link EnumUtils} class.</p>
+ *
+ * <h4>Subclassed Enums</h4>
+ * <p>A hierarchy of Enum classes can be built. In this case, the superclass is
+ * unaffected by the addition of subclasses (as per normal Java). The subclasses
+ * may add additional Enum constants <em>of the type of the superclass</em>. The
+ * query methods on the subclass will return all of the Enum constants from the
+ * superclass and subclass.</p>
+ *
+ * <pre>
+ * public final class ExtraColorEnum extends ColorEnum {
+ * // NOTE: Color enum declared above is final, change that to get this
+ * // example to compile.
+ * public static final ColorEnum YELLOW = new ExtraColorEnum("Yellow");
+ *
+ * private ExtraColorEnum(String color) {
+ * super(color);
+ * }
+ *
+ * public static ColorEnum getEnum(String color) {
+ * return (ColorEnum) getEnum(ExtraColorEnum.class, color);
+ * }
+ *
+ * public static Map getEnumMap() {
+ * return getEnumMap(ExtraColorEnum.class);
+ * }
+ *
+ * public static List getEnumList() {
+ * return getEnumList(ExtraColorEnum.class);
+ * }
+ *
+ * public static Iterator iterator() {
+ * return iterator(ExtraColorEnum.class);
+ * }
+ * }
+ * </pre>
+ *
+ * <p>This example will return RED, GREEN, BLUE, YELLOW from the List and iterator
+ * methods in that order. The RED, GREEN and BLUE instances will be the same (==)
+ * as those from the superclass ColorEnum. Note that YELLOW is declared as a
+ * ColorEnum and not an ExtraColorEnum.</p>
+ *
+ * <h4>Functional Enums</h4>
+ *
+ * <p>The enums can have functionality by defining subclasses and
+ * overriding the <code>getEnumClass()</code> method:</p>
+ *
+ * <pre>
+ * public static final OperationEnum PLUS = new PlusOperation();
+ * private static final class PlusOperation extends OperationEnum {
+ * private PlusOperation() {
+ * super("Plus");
+ * }
+ * public int eval(int a, int b) {
+ * return a + b;
+ * }
+ * }
+ * public static final OperationEnum MINUS = new MinusOperation();
+ * private static final class MinusOperation extends OperationEnum {
+ * private MinusOperation() {
+ * super("Minus");
+ * }
+ * public int eval(int a, int b) {
+ * return a - b;
+ * }
+ * }
+ *
+ * private OperationEnum(String color) {
+ * super(color);
+ * }
+ *
+ * public final Class getEnumClass() { // NOTE: new method!
+ * return OperationEnum.class;
+ * }
+ *
+ * public abstract double eval(double a, double b);
+ *
+ * public static OperationEnum getEnum(String name) {
+ * return (OperationEnum) getEnum(OperationEnum.class, name);
+ * }
+ *
+ * public static Map getEnumMap() {
+ * return getEnumMap(OperationEnum.class);
+ * }
+ *
+ * public static List getEnumList() {
+ * return getEnumList(OperationEnum.class);
+ * }
+ *
+ * public static Iterator iterator() {
+ * return iterator(OperationEnum.class);
+ * }
+ * }
+ * </pre>
+ * <p>The code above will work on JDK 1.2. If JDK1.3 and later is used,
+ * the subclasses may be defined as anonymous.</p>
+ *
+ * <h4>Nested class Enums</h4>
+ *
+ * <p>Care must be taken with class loading when defining a static nested class
+ * for enums. The static nested class can be loaded without the surrounding outer
+ * class being loaded. This can result in an empty list/map/iterator being returned.
+ * One solution is to define a static block that references the outer class where
+ * the constants are defined. For example:</p>
+ *
+ * <pre>
+ * public final class Outer {
+ * public static final BWEnum BLACK = new BWEnum("Black");
+ * public static final BWEnum WHITE = new BWEnum("White");
+ *
+ * // static nested enum class
+ * public static final class BWEnum extends Enum {
+ *
+ * static {
+ * // explicitly reference BWEnum class to force constants to load
+ * Object obj = Outer.BLACK;
+ * }
+ *
+ * // ... other methods omitted
+ * }
+ * }
+ * </pre>
+ *
+ * <p>Although the above solves the problem, it is not recommended. The best solution
+ * is to define the constants in the enum class, and hold references in the outer class:
+ *
+ * <pre>
+ * public final class Outer {
+ * public static final BWEnum BLACK = BWEnum.BLACK;
+ * public static final BWEnum WHITE = BWEnum.WHITE;
+ *
+ * // static nested enum class
+ * public static final class BWEnum extends Enum {
+ * // only define constants in enum classes - private if desired
+ * private static final BWEnum BLACK = new BWEnum("Black");
+ * private static final BWEnum WHITE = new BWEnum("White");
+ *
+ * // ... other methods omitted
+ * }
+ * }
+ * </pre>
+ *
+ * <p>For more details, see the 'Nested' test cases.
+ *
+ * @author Apache Avalon project
+ * @author Stephen Colebourne
+ * @author Chris Webb
+ * @author Mike Bowler
+ * @author Matthias Eichel
+ * @since 2.1 (class existed in enum package from v1.0)
+ * @version $Id$
+ */
+public abstract class Enum implements Comparable, Serializable {
+
+ /** Lang version 1.0.1 serial compatibility */
+ private static final long serialVersionUID = -487045951170455942L;
+
+ // After discussion, the default size for HashMaps is used, as the
+ // sizing algorithm changes across the JDK versions
+ /**
+ * An empty <code>Map</code>, as JDK1.2 didn't have an empty map.
+ */
+ private static final Map EMPTY_MAP = Collections.unmodifiableMap(new HashMap(0));
+
+ /**
+ * <code>Map</code>, key of class name, value of <code>Entry</code>.
+ */
+ private static final Map cEnumClasses = new HashMap();
+
+ /**
+ * The string representation of the Enum.
+ */
+ private final String iName;
+
+ /**
+ * The hashcode representation of the Enum.
+ */
+ private transient final int iHashCode;
+
+ /**
+ * The toString representation of the Enum.
+ * @since 2.0
+ */
+ protected transient String iToString = null;
+
+ /**
+ * <p>Enable the iterator to retain the source code order.</p>
+ */
+ private static class Entry {
+ /**
+ * Map of Enum name to Enum.
+ */
+ final Map map = new HashMap();
+ /**
+ * Map of Enum name to Enum.
+ */
+ final Map unmodifiableMap = Collections.unmodifiableMap(map);
+ /**
+ * List of Enums in source code order.
+ */
+ final List list = new ArrayList(25);
+ /**
+ * Map of Enum name to Enum.
+ */
+ final List unmodifiableList = Collections.unmodifiableList(list);
+
+ /**
+ * <p>Restrictive constructor.</p>
+ */
+ private Entry() {
+ }
+ }
+
+ /**
+ * <p>Constructor to add a new named item to the enumeration.</p>
+ *
+ * @param name the name of the enum object,
+ * must not be empty or <code>null</code>
+ * @throws IllegalArgumentException if the name is <code>null</code>
+ * or an empty string
+ * @throws IllegalArgumentException if the getEnumClass() method returns
+ * a null or invalid Class
+ */
+ protected Enum(String name) {
+ super();
+ init(name);
+ iName = name;
+ iHashCode = 7 + getEnumClass().hashCode() + 3 * name.hashCode();
+ // cannot create toString here as subclasses may want to include other data
+ }
+
+ /**
+ * Initializes the enumeration.
+ *
+ * @param name the enum name
+ * @throws IllegalArgumentException if the name is null or empty or duplicate
+ * @throws IllegalArgumentException if the enumClass is null or invalid
+ */
+ private void init(String name) {
+ if (StringUtils.isEmpty(name)) {
+ throw new IllegalArgumentException("The Enum name must not be empty or null");
+ }
+
+ Class enumClass = getEnumClass();
+ if (enumClass == null) {
+ throw new IllegalArgumentException("getEnumClass() must not be null");
+ }
+ Class cls = getClass();
+ boolean ok = false;
+ while (cls != null && cls != Enum.class && cls != ValuedEnum.class) {
+ if (cls == enumClass) {
+ ok = true;
+ break;
+ }
+ cls = cls.getSuperclass();
+ }
+ if (ok == false) {
+ throw new IllegalArgumentException("getEnumClass() must return a superclass of this class");
+ }
+
+ // create entry
+ Entry entry = (Entry) cEnumClasses.get(enumClass);
+ if (entry == null) {
+ entry = createEntry(enumClass);
+ cEnumClasses.put(enumClass, entry);
+ }
+ if (entry.map.containsKey(name)) {
+ throw new IllegalArgumentException("The Enum name must be unique, '" + name + "' has already been added");
+ }
+ entry.map.put(name, this);
+ entry.list.add(this);
+ }
+
+ /**
+ * <p>Handle the deserialization of the class to ensure that multiple
+ * copies are not wastefully created, or illegal enum types created.</p>
+ *
+ * @return the resolved object
+ */
+ protected Object readResolve() {
+ Entry entry = (Entry) cEnumClasses.get(getEnumClass());
+ if (entry == null) {
+ return null;
+ }
+ return (Enum) entry.map.get(getName());
+ }
+
+ //--------------------------------------------------------------------------------
+
+ /**
+ * <p>Gets an <code>Enum</code> object by class and name.</p>
+ *
+ * @param enumClass the class of the Enum to get, must not
+ * be <code>null</code>
+ * @param name the name of the <code>Enum</code> to get,
+ * may be <code>null</code>
+ * @return the enum object, or <code>null</code> if the enum does not exist
+ * @throws IllegalArgumentException if the enum class
+ * is <code>null</code>
+ */
+ protected static Enum getEnum(Class enumClass, String name) {
+ Entry entry = getEntry(enumClass);
+ if (entry == null) {
+ return null;
+ }
+ return (Enum) entry.map.get(name);
+ }
+
+ /**
+ * <p>Gets the <code>Map</code> of <code>Enum</code> objects by
+ * name using the <code>Enum</code> class.</p>
+ *
+ * <p>If the requested class has no enum objects an empty
+ * <code>Map</code> is returned.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get,
+ * must not be <code>null</code>
+ * @return the enum object Map
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ * @throws IllegalArgumentException if the enum class is not a subclass of Enum
+ */
+ protected static Map getEnumMap(Class enumClass) {
+ Entry entry = getEntry(enumClass);
+ if (entry == null) {
+ return EMPTY_MAP;
+ }
+ return entry.unmodifiableMap;
+ }
+
+ /**
+ * <p>Gets the <code>List</code> of <code>Enum</code> objects using the
+ * <code>Enum</code> class.</p>
+ *
+ * <p>The list is in the order that the objects were created (source code order).
+ * If the requested class has no enum objects an empty <code>List</code> is
+ * returned.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get,
+ * must not be <code>null</code>
+ * @return the enum object Map
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ * @throws IllegalArgumentException if the enum class is not a subclass of Enum
+ */
+ protected static List getEnumList(Class enumClass) {
+ Entry entry = getEntry(enumClass);
+ if (entry == null) {
+ return Collections.EMPTY_LIST;
+ }
+ return entry.unmodifiableList;
+ }
+
+ /**
+ * <p>Gets an <code>Iterator</code> over the <code>Enum</code> objects in
+ * an <code>Enum</code> class.</p>
+ *
+ * <p>The <code>Iterator</code> is in the order that the objects were
+ * created (source code order). If the requested class has no enum
+ * objects an empty <code>Iterator</code> is returned.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get,
+ * must not be <code>null</code>
+ * @return an iterator of the Enum objects
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ * @throws IllegalArgumentException if the enum class is not a subclass of Enum
+ */
+ protected static Iterator iterator(Class enumClass) {
+ return Enum.getEnumList(enumClass).iterator();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Gets an <code>Entry</code> from the map of Enums.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @return the enum entry
+ */
+ private static Entry getEntry(Class enumClass) {
+ if (enumClass == null) {
+ throw new IllegalArgumentException("The Enum Class must not be null");
+ }
+ if (Enum.class.isAssignableFrom(enumClass) == false) {
+ throw new IllegalArgumentException("The Class must be a subclass of Enum");
+ }
+ Entry entry = (Entry) cEnumClasses.get(enumClass);
+ return entry;
+ }
+
+ /**
+ * <p>Creates an <code>Entry</code> for storing the Enums.</p>
+ *
+ * <p>This accounts for subclassed Enums.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @return the enum entry
+ */
+ private static Entry createEntry(Class enumClass) {
+ Entry entry = new Entry();
+ Class cls = enumClass.getSuperclass();
+ while (cls != null && cls != Enum.class && cls != ValuedEnum.class) {
+ Entry loopEntry = (Entry) cEnumClasses.get(cls);
+ if (loopEntry != null) {
+ entry.list.addAll(loopEntry.list);
+ entry.map.putAll(loopEntry.map);
+ break; // stop here, as this will already have had superclasses added
+ }
+ cls = cls.getSuperclass();
+ }
+ return entry;
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Retrieve the name of this Enum item, set in the constructor.</p>
+ *
+ * @return the <code>String</code> name of this Enum item
+ */
+ public final String getName() {
+ return iName;
+ }
+
+ /**
+ * <p>Retrieves the Class of this Enum item, set in the constructor.</p>
+ *
+ * <p>This is normally the same as <code>getClass()</code>, but for
+ * advanced Enums may be different. If overridden, it must return a
+ * constant value.</p>
+ *
+ * @return the <code>Class</code> of the enum
+ * @since 2.0
+ */
+ public Class getEnumClass() {
+ return getClass();
+ }
+
+ /**
+ * <p>Tests for equality.</p>
+ *
+ * <p>Two Enum objects are considered equal
+ * if they have the same class names and the same names.
+ * Identity is tested for first, so this method usually runs fast.</p>
+ *
+ * <p>If the parameter is in a different class loader than this instance,
+ * reflection is used to compare the names.</p>
+ *
+ * @param other the other object to compare for equality
+ * @return <code>true</code> if the Enums are equal
+ */
+ public final boolean equals(Object other) {
+ if (other == this) {
+ return true;
+ } else if (other == null) {
+ return false;
+ } else if (other.getClass() == this.getClass()) {
+ // Ok to do a class cast to Enum here since the test above
+ // guarantee both
+ // classes are in the same class loader.
+ return iName.equals(((Enum) other).iName);
+ } else {
+ // This and other are in different class loaders, we must check indirectly
+ if (other.getClass().getName().equals(this.getClass().getName()) == false) {
+ return false;
+ }
+ try {
+ Method mth = other.getClass().getMethod("getName", null);
+ String name = (String) mth.invoke(other, null);
+ return iName.equals(name);
+ } catch (NoSuchMethodException e) {
+ // ignore - should never happen
+ } catch (IllegalAccessException e) {
+ // ignore - should never happen
+ } catch (InvocationTargetException e) {
+ // ignore - should never happen
+ }
+ return false;
+ }
+ }
+
+ /**
+ * <p>Returns a suitable hashCode for the enumeration.</p>
+ *
+ * @return a hashcode based on the name
+ */
+ public final int hashCode() {
+ return iHashCode;
+ }
+
+ /**
+ * <p>Tests for order.</p>
+ *
+ * <p>The default ordering is alphabetic by name, but this
+ * can be overridden by subclasses.</p>
+ *
+ * @see java.lang.Comparable#compareTo(Object)
+ * @param other the other object to compare to
+ * @return -ve if this is less than the other object, +ve if greater
+ * than, <code>0</code> of equal
+ * @throws ClassCastException if other is not an Enum
+ * @throws NullPointerException if other is <code>null</code>
+ */
+ public int compareTo(Object other) {
+ if (other == this) {
+ return 0;
+ }
+ return iName.compareTo(((Enum) other).iName);
+ }
+
+ /**
+ * <p>Human readable description of this Enum item.</p>
+ *
+ * @return String in the form <code>type[name]</code>, for example:
+ * <code>Color[Red]</code>. Note that the package name is stripped from
+ * the type name.
+ */
+ public String toString() {
+ if (iToString == null) {
+ String shortName = ClassUtils.getShortClassName(getEnumClass());
+ iToString = shortName + "[" + getName() + "]";
+ }
+ return iToString;
+ }
+
+}
Propchange: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/Enum.java
------------------------------------------------------------------------------
svn:keywords = HeadURL Id LastChangedBy LastChangedDate LastChangedRevision
Added: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/EnumUtils.java
URL: http://svn.apache.org/viewcvs/directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/EnumUtils.java?rev=370807&view=auto
==============================================================================
--- directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/EnumUtils.java (added)
+++ directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/EnumUtils.java Fri Jan 20 05:47:50 2006
@@ -0,0 +1,122 @@
+/*
+ * Copyright 2002-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.mina.common.support.lang.enums;
+
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * <p>Utility class for accessing and manipulating {@link Enum}s.</p>
+ *
+ * @see Enum
+ * @see ValuedEnum
+ * @author Stephen Colebourne
+ * @author Gary Gregory
+ * @since 2.1 (class existed in enum package from v1.0)
+ * @version $Id$
+ */
+public class EnumUtils {
+
+ /**
+ * Public constructor. This class should not normally be instantiated.
+ * @since 2.0
+ */
+ public EnumUtils() {
+ }
+
+ /**
+ * <p>Gets an <code>Enum</code> object by class and name.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @param name the name of the Enum to get, may be <code>null</code>
+ * @return the enum object
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ */
+ public static Enum getEnum(Class enumClass, String name) {
+ return Enum.getEnum(enumClass, name);
+ }
+
+ /**
+ * <p>Gets a <code>ValuedEnum</code> object by class and value.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @param value the value of the <code>Enum</code> to get
+ * @return the enum object, or null if the enum does not exist
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ */
+ public static ValuedEnum getEnum(Class enumClass, int value) {
+ return (ValuedEnum) ValuedEnum.getEnum(enumClass, value);
+ }
+
+ /**
+ * <p>Gets the <code>Map</code> of <code>Enum</code> objects by
+ * name using the <code>Enum</code> class.</p>
+ *
+ * <p>If the requested class has no enum objects an empty
+ * <code>Map</code> is returned. The <code>Map</code> is unmodifiable.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @return the enum object Map
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ * @throws IllegalArgumentException if the enum class is not a subclass
+ * of <code>Enum</code>
+ */
+ public static Map getEnumMap(Class enumClass) {
+ return Enum.getEnumMap(enumClass);
+ }
+
+ /**
+ * <p>Gets the <code>List</code> of <code>Enum</code> objects using
+ * the <code>Enum</code> class.</p>
+ *
+ * <p>The list is in the order that the objects were created
+ * (source code order).</p>
+ *
+ * <p>If the requested class has no enum objects an empty
+ * <code>List</code> is returned. The <code>List</code> is unmodifiable.</p>
+ *
+ * @param enumClass the class of the Enum to get
+ * @return the enum object Map
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ * @throws IllegalArgumentException if the enum class is not a subclass
+ * of <code>Enum</code>
+ */
+ public static List getEnumList(Class enumClass) {
+ return Enum.getEnumList(enumClass);
+ }
+
+ /**
+ * <p>Gets an <code>Iterator</code> over the <code>Enum</code> objects
+ * in an <code>Enum</code> class.</p>
+ *
+ * <p>The iterator is in the order that the objects were created
+ * (source code order).</p>
+ *
+ * <p>If the requested class has no enum objects an empty
+ * <code>Iterator</code> is returned. The <code>Iterator</code>
+ * is unmodifiable.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @return an <code>Iterator</code> of the <code>Enum</code> objects
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ * @throws IllegalArgumentException if the enum class is not a subclass of <code>Enum</code>
+ */
+ public static Iterator iterator(Class enumClass) {
+ return Enum.getEnumList(enumClass).iterator();
+ }
+
+}
Propchange: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/EnumUtils.java
------------------------------------------------------------------------------
svn:keywords = HeadURL Id LastChangedBy LastChangedDate LastChangedRevision
Added: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/ValuedEnum.java
URL: http://svn.apache.org/viewcvs/directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/ValuedEnum.java?rev=370807&view=auto
==============================================================================
--- directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/ValuedEnum.java (added)
+++ directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/ValuedEnum.java Fri Jan 20 05:47:50 2006
@@ -0,0 +1,190 @@
+/*
+ * Copyright 2002-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.mina.common.support.lang.enums;
+
+import java.util.Iterator;
+import java.util.List;
+
+import org.apache.mina.common.support.lang.ClassUtils;
+
+/**
+ * <p>Abstract superclass for type-safe enums with integer values suitable
+ * for use in <code>switch</code> statements.</p>
+ *
+ * <p><em>NOTE:</em>Due to the way in which Java ClassLoaders work, comparing
+ * <code>Enum</code> objects should always be done using the equals() method,
+ * not <code>==</code>. The equals() method will try <code>==</code> first so
+ * in most cases the effect is the same.</p>
+ *
+ * <p>To use this class, it must be subclassed. For example:</p>
+ *
+ * <pre>
+ * public final class JavaVersionEnum extends ValuedEnum {
+ * //standard enums for version of JVM
+ * public static final int JAVA1_0_VALUE = 100;
+ * public static final int JAVA1_1_VALUE = 110;
+ * public static final int JAVA1_2_VALUE = 120;
+ * public static final int JAVA1_3_VALUE = 130;
+ * public static final JavaVersionEnum JAVA1_0 = new JavaVersionEnum( "Java 1.0", JAVA1_0_VALUE );
+ * public static final JavaVersionEnum JAVA1_1 = new JavaVersionEnum( "Java 1.1", JAVA1_1_VALUE );
+ * public static final JavaVersionEnum JAVA1_2 = new JavaVersionEnum( "Java 1.2", JAVA1_2_VALUE );
+ * public static final JavaVersionEnum JAVA1_3 = new JavaVersionEnum( "Java 1.3", JAVA1_3_VALUE );
+ *
+ * private JavaVersionEnum(String name, int value) {
+ * super( name, value );
+ * }
+ *
+ * public static JavaVersionEnum getEnum(String javaVersion) {
+ * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
+ * }
+ *
+ * public static JavaVersionEnum getEnum(int javaVersion) {
+ * return (JavaVersionEnum) getEnum(JavaVersionEnum.class, javaVersion);
+ * }
+ *
+ * public static Map getEnumMap() {
+ * return getEnumMap(JavaVersionEnum.class);
+ * }
+ *
+ * public static List getEnumList() {
+ * return getEnumList(JavaVersionEnum.class);
+ * }
+ *
+ * public static Iterator iterator() {
+ * return iterator(JavaVersionEnum.class);
+ * }
+ * }
+ * </pre>
+ *
+ * <p><em>NOTE:</em>These are declared <code>final</code>, so compilers may
+ * inline the code. Ensure you recompile everything when using final. </p>
+ *
+ * <p>The above class could then be used as follows:</p>
+ *
+ * <pre>
+ * public void doSomething(JavaVersion ver) {
+ * switch (ver.getValue()) {
+ * case JAVA1_0_VALUE:
+ * // ...
+ * break;
+ * case JAVA1_1_VALUE:
+ * // ...
+ * break;
+ * //...
+ * }
+ * }
+ * </pre>
+ *
+ * <p>As shown, each enum has a name and a value. These can be accessed using
+ * <code>getName</code> and <code>getValue</code>.</p>
+ *
+ * <p>The <code>getEnum</code> and <code>iterator</code> methods are recommended.
+ * Unfortunately, Java restrictions require these to be coded as shown in each subclass.
+ * An alternative choice is to use the {@link EnumUtils} class.</p>
+ *
+ * @author Apache Avalon project
+ * @author Stephen Colebourne
+ * @since 2.1 (class existed in enum package from v1.0)
+ * @version $Id$
+ */
+public abstract class ValuedEnum extends Enum {
+
+ /** Lang version 1.0.1 serial compatibility */
+ private static final long serialVersionUID = -7129650521543789085L;
+
+ /**
+ * The value contained in enum.
+ */
+ private final int iValue;
+
+ /**
+ * Constructor for enum item.
+ *
+ * @param name the name of enum item
+ * @param value the value of enum item
+ */
+ protected ValuedEnum(String name, int value) {
+ super(name);
+ iValue = value;
+ }
+
+ /**
+ * <p>Gets an <code>Enum</code> object by class and value.</p>
+ *
+ * <p>This method loops through the list of <code>Enum</code>,
+ * thus if there are many <code>Enum</code>s this will be
+ * slow.</p>
+ *
+ * @param enumClass the class of the <code>Enum</code> to get
+ * @param value the value of the <code>Enum</code> to get
+ * @return the enum object, or null if the enum does not exist
+ * @throws IllegalArgumentException if the enum class is <code>null</code>
+ */
+ protected static Enum getEnum(Class enumClass, int value) {
+ if (enumClass == null) {
+ throw new IllegalArgumentException("The Enum Class must not be null");
+ }
+ List list = Enum.getEnumList(enumClass);
+ for (Iterator it = list.iterator(); it.hasNext();) {
+ ValuedEnum enumeration = (ValuedEnum) it.next();
+ if (enumeration.getValue() == value) {
+ return enumeration;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * <p>Get value of enum item.</p>
+ *
+ * @return the enum item's value.
+ */
+ public final int getValue() {
+ return iValue;
+ }
+
+ /**
+ * <p>Tests for order.</p>
+ *
+ * <p>The default ordering is numeric by value, but this
+ * can be overridden by subclasses.</p>
+ *
+ * @see java.lang.Comparable#compareTo(Object)
+ * @param other the other object to compare to
+ * @return -ve if this is less than the other object, +ve if greater than,
+ * <code>0</code> of equal
+ * @throws ClassCastException if other is not an <code>Enum</code>
+ * @throws NullPointerException if other is <code>null</code>
+ */
+ public int compareTo(Object other) {
+ return iValue - ((ValuedEnum) other).iValue;
+ }
+
+ /**
+ * <p>Human readable description of this <code>Enum</code> item.</p>
+ *
+ * @return String in the form <code>type[name=value]</code>, for example:
+ * <code>JavaVersion[Java 1.0=100]</code>. Note that the package name is
+ * stripped from the type name.
+ */
+ public String toString() {
+ if (iToString == null) {
+ String shortName = ClassUtils.getShortClassName(getEnumClass());
+ iToString = shortName + "[" + getName() + "=" + getValue() + "]";
+ }
+ return iToString;
+ }
+}
Propchange: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/ValuedEnum.java
------------------------------------------------------------------------------
svn:keywords = HeadURL Id LastChangedBy LastChangedDate LastChangedRevision
Added: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/package.html
URL: http://svn.apache.org/viewcvs/directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/package.html?rev=370807&view=auto
==============================================================================
--- directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/package.html (added)
+++ directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/package.html Fri Jan 20 05:47:50 2006
@@ -0,0 +1,53 @@
+<!--
+Copyright 2002-2005 The Apache Software Foundation.
+
+Licensed 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.
+-->
+<html>
+<body>
+<p>
+Provides an implementation of the C style <code>enum</code> in the Java world.
+</p>
+<p>
+The classic example being an RGB color enumeration.
+</p>
+<pre>
+public final class ColorEnum extends Enum {
+ public static final ColorEnum RED = new ColorEnum("Red");
+ public static final ColorEnum GREEN = new ColorEnum("Green");
+ public static final ColorEnum BLUE = new ColorEnum("Blue");
+
+ private ColorEnum(String color) {
+ super(color);
+ }
+
+ public static ColorEnum getEnum(String color) {
+ return (ColorEnum) getEnum(ColorEnum.class, color);
+ }
+
+ public static Map getEnumMap() {
+ return getEnumMap(ColorEnum.class);
+ }
+
+ public static List getEnumList() {
+ return getEnumList(ColorEnum.class);
+ }
+
+ public static Iterator iterator() {
+ return iterator(ColorEnum.class);
+ }
+}
+</pre>
+@since 2.1
+</body>
+</html>
Propchange: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/enums/package.html
------------------------------------------------------------------------------
svn:keywords = HeadURL Id LastChangedBy LastChangedDate LastChangedRevision
Added: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/ExceptionUtils.java
URL: http://svn.apache.org/viewcvs/directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/ExceptionUtils.java?rev=370807&view=auto
==============================================================================
--- directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/ExceptionUtils.java (added)
+++ directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/ExceptionUtils.java Fri Jan 20 05:47:50 2006
@@ -0,0 +1,797 @@
+/*
+ * Copyright 2002-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.mina.common.support.lang.exception;
+
+import java.io.PrintStream;
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import java.lang.reflect.Field;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.StringTokenizer;
+
+import org.apache.mina.common.support.lang.ArrayUtils;
+import org.apache.mina.common.support.lang.StringUtils;
+import org.apache.mina.common.support.lang.SystemUtils;
+
+/**
+ * <p>Provides utilities for manipulating and examining
+ * <code>Throwable</code> objects.</p>
+ *
+ * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
+ * @author Dmitri Plotnikov
+ * @author Stephen Colebourne
+ * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a>
+ * @author Pete Gieser
+ * @since 1.0
+ * @version $Id$
+ */
+public class ExceptionUtils {
+
+ /**
+ * <p>Used when printing stack frames to denote the start of a
+ * wrapped exception.</p>
+ *
+ * <p>Package private for accessibility by test suite.</p>
+ */
+ static final String WRAPPED_MARKER = " [wrapped] ";
+
+ /**
+ * <p>The names of methods commonly used to access a wrapped exception.</p>
+ */
+ private static String[] CAUSE_METHOD_NAMES = {
+ "getCause",
+ "getNextException",
+ "getTargetException",
+ "getException",
+ "getSourceException",
+ "getRootCause",
+ "getCausedByException",
+ "getNested",
+ "getLinkedException",
+ "getNestedException",
+ "getLinkedCause",
+ "getThrowable",
+ };
+
+ /**
+ * <p>The Method object for JDK1.4 getCause.</p>
+ */
+ private static final Method THROWABLE_CAUSE_METHOD;
+ static {
+ Method getCauseMethod;
+ try {
+ getCauseMethod = Throwable.class.getMethod("getCause", null);
+ } catch (Exception e) {
+ getCauseMethod = null;
+ }
+ THROWABLE_CAUSE_METHOD = getCauseMethod;
+ }
+
+ /**
+ * <p>Public constructor allows an instance of <code>ExceptionUtils</code>
+ * to be created, although that is not normally necessary.</p>
+ */
+ public ExceptionUtils() {
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Adds to the list of method names used in the search for <code>Throwable</code>
+ * objects.</p>
+ *
+ * @param methodName the methodName to add to the list, <code>null</code>
+ * and empty strings are ignored
+ * @since 2.0
+ */
+ public static void addCauseMethodName(String methodName) {
+ if (StringUtils.isNotEmpty(methodName) && !isCauseMethodName(methodName)) {
+ List list = getCauseMethodNameList();
+ if (list.add(methodName)) {
+ CAUSE_METHOD_NAMES = toArray(list);
+ }
+ }
+ }
+
+ /**
+ * <p>Removes from the list of method names used in the search for <code>Throwable</code>
+ * objects.</p>
+ *
+ * @param methodName the methodName to remove from the list, <code>null</code>
+ * and empty strings are ignored
+ * @since 2.1
+ */
+ public static void removeCauseMethodName(String methodName) {
+ if (StringUtils.isNotEmpty(methodName)) {
+ List list = getCauseMethodNameList();
+ if (list.remove(methodName)) {
+ CAUSE_METHOD_NAMES = toArray(list);
+ }
+ }
+ }
+
+ /**
+ * Returns the given list as a <code>String[]</code>.
+ * @param list a list to transform.
+ * @return the given list as a <code>String[]</code>.
+ */
+ private static String[] toArray(List list) {
+ return (String[]) list.toArray(new String[list.size()]);
+ }
+
+ /**
+ * Returns {@link #CAUSE_METHOD_NAMES} as a List.
+ * @return {@link #CAUSE_METHOD_NAMES} as a List.
+ */
+ private static ArrayList getCauseMethodNameList() {
+ return new ArrayList(Arrays.asList(CAUSE_METHOD_NAMES));
+ }
+
+ /**
+ * <p>Tests if the list of method names used in the search for <code>Throwable</code>
+ * objects include the given name.</p>
+ *
+ * @param methodName the methodName to search in the list.
+ * @return if the list of method names used in the search for <code>Throwable</code>
+ * objects include the given name.
+ * @since 2.1
+ */
+ public static boolean isCauseMethodName(String methodName) {
+ return ArrayUtils.indexOf(CAUSE_METHOD_NAMES, methodName) >= 0;
+ }
+
+ /**
+ * <p>Introspects the <code>Throwable</code> to obtain the cause.</p>
+ *
+ * <p>The method searches for methods with specific names that return a
+ * <code>Throwable</code> object. This will pick up most wrapping exceptions,
+ * including those from JDK 1.4, and
+ * {@link org.apache.mina.common.support.lang.exception.NestableException NestableException}.
+ * The method names can be added to using {@link #addCauseMethodName(String)}.</p>
+ *
+ * <p>The default list searched for are:</p>
+ * <ul>
+ * <li><code>getCause()</code></li>
+ * <li><code>getNextException()</code></li>
+ * <li><code>getTargetException()</code></li>
+ * <li><code>getException()</code></li>
+ * <li><code>getSourceException()</code></li>
+ * <li><code>getRootCause()</code></li>
+ * <li><code>getCausedByException()</code></li>
+ * <li><code>getNested()</code></li>
+ * </ul>
+ *
+ * <p>In the absence of any such method, the object is inspected for a
+ * <code>detail</code> field assignable to a <code>Throwable</code>.</p>
+ *
+ * <p>If none of the above is found, returns <code>null</code>.</p>
+ *
+ * @param throwable the throwable to introspect for a cause, may be null
+ * @return the cause of the <code>Throwable</code>,
+ * <code>null</code> if none found or null throwable input
+ * @since 1.0
+ */
+ public static Throwable getCause(Throwable throwable) {
+ return getCause(throwable, CAUSE_METHOD_NAMES);
+ }
+
+ /**
+ * <p>Introspects the <code>Throwable</code> to obtain the cause.</p>
+ *
+ * <ol>
+ * <li>Try known exception types.</li>
+ * <li>Try the supplied array of method names.</li>
+ * <li>Try the field 'detail'.</li>
+ * </ol>
+ *
+ * <p>A <code>null</code> set of method names means use the default set.
+ * A <code>null</code> in the set of method names will be ignored.</p>
+ *
+ * @param throwable the throwable to introspect for a cause, may be null
+ * @param methodNames the method names, null treated as default set
+ * @return the cause of the <code>Throwable</code>,
+ * <code>null</code> if none found or null throwable input
+ * @since 1.0
+ */
+ public static Throwable getCause(Throwable throwable, String[] methodNames) {
+ if (throwable == null) {
+ return null;
+ }
+ Throwable cause = getCauseUsingWellKnownTypes(throwable);
+ if (cause == null) {
+ if (methodNames == null) {
+ methodNames = CAUSE_METHOD_NAMES;
+ }
+ for (int i = 0; i < methodNames.length; i++) {
+ String methodName = methodNames[i];
+ if (methodName != null) {
+ cause = getCauseUsingMethodName(throwable, methodName);
+ if (cause != null) {
+ break;
+ }
+ }
+ }
+
+ if (cause == null) {
+ cause = getCauseUsingFieldName(throwable, "detail");
+ }
+ }
+ return cause;
+ }
+
+ /**
+ * <p>Introspects the <code>Throwable</code> to obtain the root cause.</p>
+ *
+ * <p>This method walks through the exception chain to the last element,
+ * "root" of the tree, using {@link #getCause(Throwable)}, and
+ * returns that exception.</p>
+ *
+ * @param throwable the throwable to get the root cause for, may be null
+ * @return the root cause of the <code>Throwable</code>,
+ * <code>null</code> if none found or null throwable input
+ */
+ public static Throwable getRootCause(Throwable throwable) {
+ Throwable cause = getCause(throwable);
+ if (cause != null) {
+ throwable = cause;
+ while ((throwable = getCause(throwable)) != null) {
+ cause = throwable;
+ }
+ }
+ return cause;
+ }
+
+ /**
+ * <p>Finds a <code>Throwable</code> for known types.</p>
+ *
+ * <p>Uses <code>instanceof</code> checks to examine the exception,
+ * looking for well known types which could contain chained or
+ * wrapped exceptions.</p>
+ *
+ * @param throwable the exception to examine
+ * @return the wrapped exception, or <code>null</code> if not found
+ */
+ private static Throwable getCauseUsingWellKnownTypes(Throwable throwable) {
+ if (throwable instanceof Nestable) {
+ return ((Nestable) throwable).getCause();
+ } else if (throwable instanceof SQLException) {
+ return ((SQLException) throwable).getNextException();
+ } else if (throwable instanceof InvocationTargetException) {
+ return ((InvocationTargetException) throwable).getTargetException();
+ } else {
+ return null;
+ }
+ }
+
+ /**
+ * <p>Finds a <code>Throwable</code> by method name.</p>
+ *
+ * @param throwable the exception to examine
+ * @param methodName the name of the method to find and invoke
+ * @return the wrapped exception, or <code>null</code> if not found
+ */
+ private static Throwable getCauseUsingMethodName(Throwable throwable, String methodName) {
+ Method method = null;
+ try {
+ method = throwable.getClass().getMethod(methodName, null);
+ } catch (NoSuchMethodException ignored) {
+ } catch (SecurityException ignored) {
+ }
+
+ if (method != null && Throwable.class.isAssignableFrom(method.getReturnType())) {
+ try {
+ return (Throwable) method.invoke(throwable, ArrayUtils.EMPTY_OBJECT_ARRAY);
+ } catch (IllegalAccessException ignored) {
+ } catch (IllegalArgumentException ignored) {
+ } catch (InvocationTargetException ignored) {
+ }
+ }
+ return null;
+ }
+
+ /**
+ * <p>Finds a <code>Throwable</code> by field name.</p>
+ *
+ * @param throwable the exception to examine
+ * @param fieldName the name of the attribute to examine
+ * @return the wrapped exception, or <code>null</code> if not found
+ */
+ private static Throwable getCauseUsingFieldName(Throwable throwable, String fieldName) {
+ Field field = null;
+ try {
+ field = throwable.getClass().getField(fieldName);
+ } catch (NoSuchFieldException ignored) {
+ } catch (SecurityException ignored) {
+ }
+
+ if (field != null && Throwable.class.isAssignableFrom(field.getType())) {
+ try {
+ return (Throwable) field.get(throwable);
+ } catch (IllegalAccessException ignored) {
+ } catch (IllegalArgumentException ignored) {
+ }
+ }
+ return null;
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Checks if the Throwable class has a <code>getCause</code> method.</p>
+ *
+ * <p>This is true for JDK 1.4 and above.</p>
+ *
+ * @return true if Throwable is nestable
+ * @since 2.0
+ */
+ public static boolean isThrowableNested() {
+ return THROWABLE_CAUSE_METHOD != null;
+ }
+
+ /**
+ * <p>Checks whether this <code>Throwable</code> class can store a cause.</p>
+ *
+ * <p>This method does <b>not</b> check whether it actually does store a cause.<p>
+ *
+ * @param throwable the <code>Throwable</code> to examine, may be null
+ * @return boolean <code>true</code> if nested otherwise <code>false</code>
+ * @since 2.0
+ */
+ public static boolean isNestedThrowable(Throwable throwable) {
+ if (throwable == null) {
+ return false;
+ }
+
+ if (throwable instanceof Nestable) {
+ return true;
+ } else if (throwable instanceof SQLException) {
+ return true;
+ } else if (throwable instanceof InvocationTargetException) {
+ return true;
+ } else if (isThrowableNested()) {
+ return true;
+ }
+
+ Class cls = throwable.getClass();
+ for (int i = 0, isize = CAUSE_METHOD_NAMES.length; i < isize; i++) {
+ try {
+ Method method = cls.getMethod(CAUSE_METHOD_NAMES[i], null);
+ if (method != null && Throwable.class.isAssignableFrom(method.getReturnType())) {
+ return true;
+ }
+ } catch (NoSuchMethodException ignored) {
+ } catch (SecurityException ignored) {
+ }
+ }
+
+ try {
+ Field field = cls.getField("detail");
+ if (field != null) {
+ return true;
+ }
+ } catch (NoSuchFieldException ignored) {
+ } catch (SecurityException ignored) {
+ }
+
+ return false;
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Counts the number of <code>Throwable</code> objects in the
+ * exception chain.</p>
+ *
+ * <p>A throwable without cause will return <code>1</code>.
+ * A throwable with one cause will return <code>2</code> and so on.
+ * A <code>null</code> throwable will return <code>0</code>.</p>
+ *
+ * @param throwable the throwable to inspect, may be null
+ * @return the count of throwables, zero if null input
+ */
+ public static int getThrowableCount(Throwable throwable) {
+ int count = 0;
+ while (throwable != null) {
+ count++;
+ throwable = ExceptionUtils.getCause(throwable);
+ }
+ return count;
+ }
+
+ /**
+ * <p>Returns the list of <code>Throwable</code> objects in the
+ * exception chain.</p>
+ *
+ * <p>A throwable without cause will return an array containing
+ * one element - the input throwable.
+ * A throwable with one cause will return an array containing
+ * two elements. - the input throwable and the cause throwable.
+ * A <code>null</code> throwable will return an array size zero.</p>
+ *
+ * @param throwable the throwable to inspect, may be null
+ * @return the array of throwables, never null
+ */
+ public static Throwable[] getThrowables(Throwable throwable) {
+ List list = new ArrayList();
+ while (throwable != null) {
+ list.add(throwable);
+ throwable = ExceptionUtils.getCause(throwable);
+ }
+ return (Throwable[]) list.toArray(new Throwable[list.size()]);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Returns the (zero based) index of the first <code>Throwable</code>
+ * that matches the specified class (exactly) in the exception chain.
+ * Subclasses of the specified class do not match - see
+ * {@link #indexOfType(Throwable, Class)} for the opposite.</p>
+ *
+ * <p>A <code>null</code> throwable returns <code>-1</code>.
+ * A <code>null</code> type returns <code>-1</code>.
+ * No match in the chain returns <code>-1</code>.</p>
+ *
+ * @param throwable the throwable to inspect, may be null
+ * @param clazz the class to search for, subclasses do not match, null returns -1
+ * @return the index into the throwable chain, -1 if no match or null input
+ */
+ public static int indexOfThrowable(Throwable throwable, Class clazz) {
+ return indexOf(throwable, clazz, 0, false);
+ }
+
+ /**
+ * <p>Returns the (zero based) index of the first <code>Throwable</code>
+ * that matches the specified type in the exception chain from
+ * a specified index.
+ * Subclasses of the specified class do not match - see
+ * {@link #indexOfType(Throwable, Class, int)} for the opposite.</p>
+ *
+ * <p>A <code>null</code> throwable returns <code>-1</code>.
+ * A <code>null</code> type returns <code>-1</code>.
+ * No match in the chain returns <code>-1</code>.
+ * A negative start index is treated as zero.
+ * A start index greater than the number of throwables returns <code>-1</code>.</p>
+ *
+ * @param throwable the throwable to inspect, may be null
+ * @param clazz the class to search for, subclasses do not match, null returns -1
+ * @param fromIndex the (zero based) index of the starting position,
+ * negative treated as zero, larger than chain size returns -1
+ * @return the index into the throwable chain, -1 if no match or null input
+ */
+ public static int indexOfThrowable(Throwable throwable, Class clazz, int fromIndex) {
+ return indexOf(throwable, clazz, fromIndex, false);
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Returns the (zero based) index of the first <code>Throwable</code>
+ * that matches the specified class or subclass in the exception chain.
+ * Subclasses of the specified class do match - see
+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite.</p>
+ *
+ * <p>A <code>null</code> throwable returns <code>-1</code>.
+ * A <code>null</code> type returns <code>-1</code>.
+ * No match in the chain returns <code>-1</code>.</p>
+ *
+ * @param throwable the throwable to inspect, may be null
+ * @param type the type to search for, subclasses match, null returns -1
+ * @return the index into the throwable chain, -1 if no match or null input
+ * @since 2.1
+ */
+ public static int indexOfType(Throwable throwable, Class type) {
+ return indexOf(throwable, type, 0, true);
+ }
+
+ /**
+ * <p>Returns the (zero based) index of the first <code>Throwable</code>
+ * that matches the specified type in the exception chain from
+ * a specified index.
+ * Subclasses of the specified class do match - see
+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite.</p>
+ *
+ * <p>A <code>null</code> throwable returns <code>-1</code>.
+ * A <code>null</code> type returns <code>-1</code>.
+ * No match in the chain returns <code>-1</code>.
+ * A negative start index is treated as zero.
+ * A start index greater than the number of throwables returns <code>-1</code>.</p>
+ *
+ * @param throwable the throwable to inspect, may be null
+ * @param type the type to search for, subclasses match, null returns -1
+ * @param fromIndex the (zero based) index of the starting position,
+ * negative treated as zero, larger than chain size returns -1
+ * @return the index into the throwable chain, -1 if no match or null input
+ * @since 2.1
+ */
+ public static int indexOfType(Throwable throwable, Class type, int fromIndex) {
+ return indexOf(throwable, type, fromIndex, true);
+ }
+
+ private static int indexOf(Throwable throwable, Class type, int fromIndex, boolean subclass) {
+ if (throwable == null || type == null) {
+ return -1;
+ }
+ if (fromIndex < 0) {
+ fromIndex = 0;
+ }
+ Throwable[] throwables = ExceptionUtils.getThrowables(throwable);
+ if (fromIndex >= throwables.length) {
+ return -1;
+ }
+ if (subclass) {
+ for (int i = fromIndex; i < throwables.length; i++) {
+ if (type.isAssignableFrom(throwables[i].getClass())) {
+ return i;
+ }
+ }
+ } else {
+ for (int i = fromIndex; i < throwables.length; i++) {
+ if (type.equals(throwables[i].getClass())) {
+ return i;
+ }
+ }
+ }
+ return -1;
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Prints a compact stack trace for the root cause of a throwable
+ * to <code>System.err</code>.</p>
+ *
+ * <p>The compact stack trace starts with the root cause and prints
+ * stack frames up to the place where it was caught and wrapped.
+ * Then it prints the wrapped exception and continues with stack frames
+ * until the wrapper exception is caught and wrapped again, etc.</p>
+ *
+ * <p>The method is equivalent to <code>printStackTrace</code> for throwables
+ * that don't have nested causes.</p>
+ *
+ * @param throwable the throwable to output
+ * @since 2.0
+ */
+ public static void printRootCauseStackTrace(Throwable throwable) {
+ printRootCauseStackTrace(throwable, System.err);
+ }
+
+ /**
+ * <p>Prints a compact stack trace for the root cause of a throwable.</p>
+ *
+ * <p>The compact stack trace starts with the root cause and prints
+ * stack frames up to the place where it was caught and wrapped.
+ * Then it prints the wrapped exception and continues with stack frames
+ * until the wrapper exception is caught and wrapped again, etc.</p>
+ *
+ * <p>The method is equivalent to <code>printStackTrace</code> for throwables
+ * that don't have nested causes.</p>
+ *
+ * @param throwable the throwable to output, may be null
+ * @param stream the stream to output to, may not be null
+ * @throws IllegalArgumentException if the stream is <code>null</code>
+ * @since 2.0
+ */
+ public static void printRootCauseStackTrace(Throwable throwable, PrintStream stream) {
+ if (throwable == null) {
+ return;
+ }
+ if (stream == null) {
+ throw new IllegalArgumentException("The PrintStream must not be null");
+ }
+ String trace[] = getRootCauseStackTrace(throwable);
+ for (int i = 0; i < trace.length; i++) {
+ stream.println(trace[i]);
+ }
+ stream.flush();
+ }
+
+ /**
+ * <p>Prints a compact stack trace for the root cause of a throwable.</p>
+ *
+ * <p>The compact stack trace starts with the root cause and prints
+ * stack frames up to the place where it was caught and wrapped.
+ * Then it prints the wrapped exception and continues with stack frames
+ * until the wrapper exception is caught and wrapped again, etc.</p>
+ *
+ * <p>The method is equivalent to <code>printStackTrace</code> for throwables
+ * that don't have nested causes.</p>
+ *
+ * @param throwable the throwable to output, may be null
+ * @param writer the writer to output to, may not be null
+ * @throws IllegalArgumentException if the writer is <code>null</code>
+ * @since 2.0
+ */
+ public static void printRootCauseStackTrace(Throwable throwable, PrintWriter writer) {
+ if (throwable == null) {
+ return;
+ }
+ if (writer == null) {
+ throw new IllegalArgumentException("The PrintWriter must not be null");
+ }
+ String trace[] = getRootCauseStackTrace(throwable);
+ for (int i = 0; i < trace.length; i++) {
+ writer.println(trace[i]);
+ }
+ writer.flush();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Creates a compact stack trace for the root cause of the supplied
+ * <code>Throwable</code>.</p>
+ *
+ * @param throwable the throwable to examine, may be null
+ * @return an array of stack trace frames, never null
+ * @since 2.0
+ */
+ public static String[] getRootCauseStackTrace(Throwable throwable) {
+ if (throwable == null) {
+ return ArrayUtils.EMPTY_STRING_ARRAY;
+ }
+ Throwable throwables[] = getThrowables(throwable);
+ int count = throwables.length;
+ ArrayList frames = new ArrayList();
+ List nextTrace = getStackFrameList(throwables[count - 1]);
+ for (int i = count; --i >= 0;) {
+ List trace = nextTrace;
+ if (i != 0) {
+ nextTrace = getStackFrameList(throwables[i - 1]);
+ removeCommonFrames(trace, nextTrace);
+ }
+ if (i == count - 1) {
+ frames.add(throwables[i].toString());
+ } else {
+ frames.add(WRAPPED_MARKER + throwables[i].toString());
+ }
+ for (int j = 0; j < trace.size(); j++) {
+ frames.add(trace.get(j));
+ }
+ }
+ return (String[]) frames.toArray(new String[0]);
+ }
+
+ /**
+ * <p>Removes common frames from the cause trace given the two stack traces.</p>
+ *
+ * @param causeFrames stack trace of a cause throwable
+ * @param wrapperFrames stack trace of a wrapper throwable
+ * @throws IllegalArgumentException if either argument is null
+ * @since 2.0
+ */
+ public static void removeCommonFrames(List causeFrames, List wrapperFrames) {
+ if (causeFrames == null || wrapperFrames == null) {
+ throw new IllegalArgumentException("The List must not be null");
+ }
+ int causeFrameIndex = causeFrames.size() - 1;
+ int wrapperFrameIndex = wrapperFrames.size() - 1;
+ while (causeFrameIndex >= 0 && wrapperFrameIndex >= 0) {
+ // Remove the frame from the cause trace if it is the same
+ // as in the wrapper trace
+ String causeFrame = (String) causeFrames.get(causeFrameIndex);
+ String wrapperFrame = (String) wrapperFrames.get(wrapperFrameIndex);
+ if (causeFrame.equals(wrapperFrame)) {
+ causeFrames.remove(causeFrameIndex);
+ }
+ causeFrameIndex--;
+ wrapperFrameIndex--;
+ }
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Gets the stack trace from a Throwable as a String.</p>
+ *
+ * @param throwable the <code>Throwable</code> to be examined
+ * @return the stack trace as generated by the exception's
+ * <code>printStackTrace(PrintWriter)</code> method
+ */
+ public static String getStackTrace(Throwable throwable) {
+ StringWriter sw = new StringWriter();
+ PrintWriter pw = new PrintWriter(sw, true);
+ throwable.printStackTrace(pw);
+ return sw.getBuffer().toString();
+ }
+
+ /**
+ * <p>A way to get the entire nested stack-trace of an throwable.</p>
+ *
+ * @param throwable the <code>Throwable</code> to be examined
+ * @return the nested stack trace, with the root cause first
+ * @since 2.0
+ */
+ public static String getFullStackTrace(Throwable throwable) {
+ StringWriter sw = new StringWriter();
+ PrintWriter pw = new PrintWriter(sw, true);
+ Throwable[] ts = getThrowables(throwable);
+ for (int i = 0; i < ts.length; i++) {
+ ts[i].printStackTrace(pw);
+ if (isNestedThrowable(ts[i])) {
+ break;
+ }
+ }
+ return sw.getBuffer().toString();
+ }
+
+ //-----------------------------------------------------------------------
+ /**
+ * <p>Captures the stack trace associated with the specified
+ * <code>Throwable</code> object, decomposing it into a list of
+ * stack frames.</p>
+ *
+ * @param throwable the <code>Throwable</code> to examine, may be null
+ * @return an array of strings describing each stack frame, never null
+ */
+ public static String[] getStackFrames(Throwable throwable) {
+ if (throwable == null) {
+ return ArrayUtils.EMPTY_STRING_ARRAY;
+ }
+ return getStackFrames(getStackTrace(throwable));
+ }
+
+ /**
+ * <p>Returns an array where each element is a line from the argument.</p>
+ * <p>The end of line is determined by the value of {@link SystemUtils#LINE_SEPARATOR}.</p>
+ *
+ * <p>Functionality shared between the
+ * <code>getStackFrames(Throwable)</code> methods of this and the
+ * {@link org.apache.mina.common.support.lang.exception.NestableDelegate}
+ * classes.</p>
+ * @param stackTrace A stack trace String.
+ * @return an array where each element is a line from the argument.
+ */
+ static String[] getStackFrames(String stackTrace) {
+ String linebreak = SystemUtils.LINE_SEPARATOR;
+ StringTokenizer frames = new StringTokenizer(stackTrace, linebreak);
+ List list = new LinkedList();
+ while (frames.hasMoreTokens()) {
+ list.add(frames.nextToken());
+ }
+ return toArray(list);
+ }
+
+ /**
+ * <p>Produces a <code>List</code> of stack frames - the message
+ * is not included.</p>
+ *
+ * <p>This works in most cases - it will only fail if the exception
+ * message contains a line that starts with:
+ * <code>" at".</code></p>
+ *
+ * @param t is any throwable
+ * @return List of stack frames
+ */
+ static List getStackFrameList(Throwable t) {
+ String stackTrace = getStackTrace(t);
+ String linebreak = SystemUtils.LINE_SEPARATOR;
+ StringTokenizer frames = new StringTokenizer(stackTrace, linebreak);
+ List list = new LinkedList();
+ boolean traceStarted = false;
+ while (frames.hasMoreTokens()) {
+ String token = frames.nextToken();
+ // Determine if the line starts with <whitespace>at
+ int at = token.indexOf("at");
+ if (at != -1 && token.substring(0, at).trim().length() == 0) {
+ traceStarted = true;
+ list.add(token);
+ } else if (traceStarted) {
+ break;
+ }
+ }
+ return list;
+ }
+
+}
Propchange: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/ExceptionUtils.java
------------------------------------------------------------------------------
svn:keywords = HeadURL Id LastChangedBy LastChangedDate LastChangedRevision
Added: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/Nestable.java
URL: http://svn.apache.org/viewcvs/directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/Nestable.java?rev=370807&view=auto
==============================================================================
--- directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/Nestable.java (added)
+++ directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/Nestable.java Fri Jan 20 05:47:50 2006
@@ -0,0 +1,177 @@
+/*
+ * Copyright 2002-2005 The Apache Software Foundation.
+ *
+ * Licensed 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.mina.common.support.lang.exception;
+
+import java.io.PrintStream;
+import java.io.PrintWriter;
+
+/**
+ * An interface to be implemented by {@link java.lang.Throwable}
+ * extensions which would like to be able to nest root exceptions
+ * inside themselves.
+ *
+ * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
+ * @author <a href="mailto:knielsen@apache.org">Kasper Nielsen</a>
+ * @author <a href="mailto:steven@caswell.name">Steven Caswell</a>
+ * @author Pete Gieser
+ * @since 1.0
+ * @version $Id$
+ */
+public interface Nestable {
+
+ /**
+ * Returns the reference to the exception or error that caused the
+ * exception implementing the <code>Nestable</code> to be thrown.
+ *
+ * @return throwable that caused the original exception
+ */
+ public Throwable getCause();
+
+ /**
+ * Returns the error message of this and any nested
+ * <code>Throwable</code>.
+ *
+ * @return the error message
+ */
+ public String getMessage();
+
+ /**
+ * Returns the error message of the <code>Throwable</code> in the chain
+ * of <code>Throwable</code>s at the specified index, numbered from 0.
+ *
+ * @param index the index of the <code>Throwable</code> in the chain of
+ * <code>Throwable</code>s
+ * @return the error message, or null if the <code>Throwable</code> at the
+ * specified index in the chain does not contain a message
+ * @throws IndexOutOfBoundsException if the <code>index</code> argument is
+ * negative or not less than the count of <code>Throwable</code>s in the
+ * chain
+ */
+ public String getMessage(int index);
+
+ /**
+ * Returns the error message of this and any nested <code>Throwable</code>s
+ * in an array of Strings, one element for each message. Any
+ * <code>Throwable</code> not containing a message is represented in the
+ * array by a null. This has the effect of cause the length of the returned
+ * array to be equal to the result of the {@link #getThrowableCount()}
+ * operation.
+ *
+ * @return the error messages
+ */
+ public String[] getMessages();
+
+ /**
+ * Returns the <code>Throwable</code> in the chain of
+ * <code>Throwable</code>s at the specified index, numbered from 0.
+ *
+ * @param index the index, numbered from 0, of the <code>Throwable</code> in
+ * the chain of <code>Throwable</code>s
+ * @return the <code>Throwable</code>
+ * @throws IndexOutOfBoundsException if the <code>index</code> argument is
+ * negative or not less than the count of <code>Throwable</code>s in the
+ * chain
+ */
+ public Throwable getThrowable(int index);
+
+ /**
+ * Returns the number of nested <code>Throwable</code>s represented by
+ * this <code>Nestable</code>, including this <code>Nestable</code>.
+ *
+ * @return the throwable count
+ */
+ public int getThrowableCount();
+
+ /**
+ * Returns this <code>Nestable</code> and any nested <code>Throwable</code>s
+ * in an array of <code>Throwable</code>s, one element for each
+ * <code>Throwable</code>.
+ *
+ * @return the <code>Throwable</code>s
+ */
+ public Throwable[] getThrowables();
+
+ /**
+ * Returns the index, numbered from 0, of the first occurrence of the
+ * specified type, or a subclass, in the chain of <code>Throwable</code>s.
+ * The method returns -1 if the specified type is not found in the chain.
+ * <p>
+ * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
+ * such that this method matches subclasses.
+ * If you want to NOT match subclasses, please use
+ * {@link ExceptionUtils#indexOfThrowable(Throwable, Class)}
+ * (which is avaiable in all versions of lang).
+ *
+ * @param type the type to find, subclasses match, null returns -1
+ * @return index of the first occurrence of the type in the chain, or -1 if
+ * the type is not found
+ */
+ public int indexOfThrowable(Class type);
+
+ /**
+ * Returns the index, numbered from 0, of the first <code>Throwable</code>
+ * that matches the specified type, or a subclass, in the chain of <code>Throwable</code>s
+ * with an index greater than or equal to the specified index.
+ * The method returns -1 if the specified type is not found in the chain.
+ * <p>
+ * NOTE: From v2.1, we have clarified the <code>Nestable</code> interface
+ * such that this method matches subclasses.
+ * If you want to NOT match subclasses, please use
+ * {@link ExceptionUtils#indexOfThrowable(Throwable, Class, int)}
+ * (which is avaiable in all versions of lang).
+ *
+ * @param type the type to find, subclasses match, null returns -1
+ * @param fromIndex the index, numbered from 0, of the starting position in
+ * the chain to be searched
+ * @return index of the first occurrence of the type in the chain, or -1 if
+ * the type is not found
+ * @throws IndexOutOfBoundsException if the <code>fromIndex</code> argument
+ * is negative or not less than the count of <code>Throwable</code>s in the
+ * chain
+ */
+ public int indexOfThrowable(Class type, int fromIndex);
+
+ /**
+ * Prints the stack trace of this exception to the specified print
+ * writer. Includes information from the exception, if any,
+ * which caused this exception.
+ *
+ * @param out <code>PrintWriter</code> to use for output.
+ */
+ public void printStackTrace(PrintWriter out);
+
+ /**
+ * Prints the stack trace of this exception to the specified print
+ * stream. Includes information from the exception, if any,
+ * which caused this exception.
+ *
+ * @param out <code>PrintStream</code> to use for output.
+ */
+ public void printStackTrace(PrintStream out);
+
+ /**
+ * Prints the stack trace for this exception only--root cause not
+ * included--using the provided writer. Used by
+ * {@link org.apache.mina.common.support.lang.exception.NestableDelegate} to write
+ * individual stack traces to a buffer. The implementation of
+ * this method should call
+ * <code>super.printStackTrace(out);</code> in most cases.
+ *
+ * @param out The writer to use.
+ */
+ public void printPartialStackTrace(PrintWriter out);
+
+}
Propchange: directory/sandbox/trustin/mina-spi/core/src/main/java/org/apache/mina/common/support/lang/exception/Nestable.java
------------------------------------------------------------------------------
svn:keywords = HeadURL Id LastChangedBy LastChangedDate LastChangedRevision