EnumSyntax.java

/*
 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */


package javax.print.attribute;

import java.io.InvalidObjectException;
import java.io.ObjectStreamException;
import java.io.Serializable;

/**
 * Class EnumSyntax is an abstract base class providing the common
 * implementation of all "type safe enumeration" objects. An enumeration class
 * (which extends class EnumSyntax) provides a group of enumeration values
 * (objects) that are singleton instances of the enumeration class; for example:
 * <PRE>
 *     public class Bach extends EnumSyntax {
 *         public static final Bach JOHANN_SEBASTIAN     = new Bach(0);
 *         public static final Bach WILHELM_FRIEDEMANN   = new Bach(1);
 *         public static final Bach CARL_PHILIP_EMMANUEL = new Bach(2);
 *         public static final Bach JOHANN_CHRISTIAN     = new Bach(3);
 *         public static final Bach P_D_Q                = new Bach(4);
 *
 *         private static final String[] stringTable = {
 *             "Johann Sebastian Bach",
 *              "Wilhelm Friedemann Bach",
 *              "Carl Philip Emmanuel Bach",
 *              "Johann Christian Bach",
 *              "P.D.Q. Bach"
 *         };
 *
 *         protected String[] getStringTable() {
 *             return stringTable;
 *         }
 *
 *         private static final Bach[] enumValueTable = {
 *             JOHANN_SEBASTIAN,
 *              WILHELM_FRIEDEMANN,
 *              CARL_PHILIP_EMMANUEL,
 *              JOHANN_CHRISTIAN,
 *              P_D_Q
 *         };
 *
 *         protected EnumSyntax[] getEnumValueTable() {
 *             return enumValueTable;
 *         }
 *     }
 * </PRE>
 * You can then write code that uses the <CODE>==</CODE> and <CODE>!=</CODE>
 * operators to test enumeration values; for example:
 * <PRE>
 *     Bach theComposer;
 *     . . .
 *     if (theComposer == Bach.JOHANN_SEBASTIAN) {
 *         System.out.println ("The greatest composer of all time!");
 *     }
 * </PRE>
 * The <CODE>equals()</CODE> method for an enumeration class just does a test
 * for identical objects (<CODE>==</CODE>).
 * <P>
 * You can convert an enumeration value to a string by calling {@link
 * #toString() toString()}. The string is obtained from a table
 * supplied by the enumeration class.
 * <P>
 * Under the hood, an enumeration value is just an integer, a different integer
 * for each enumeration value within an enumeration class. You can get an
 * enumeration value's integer value by calling {@link #getValue()
 * getValue()}. An enumeration value's integer value is established
 * when it is constructed (see {@link #EnumSyntax(int)
 * EnumSyntax(int)}). Since the constructor is protected, the only
 * possible enumeration values are the singleton objects declared in the
 * enumeration class; additional enumeration values cannot be created at run
 * time.
 * <P>
 * You can define a subclass of an enumeration class that extends it with
 * additional enumeration values. The subclass's enumeration values' integer
 * values need not be distinct from the superclass's enumeration values' integer
 * values; the <CODE>==</CODE>, <CODE>!=</CODE>, <CODE>equals()</CODE>, and
 * <CODE>toString()</CODE> methods will still work properly even if the subclass
 * uses some of the same integer values as the superclass. However, the
 * application in which the enumeration class and subclass are used may need to
 * have distinct integer values in the superclass and subclass.
 * <P>
 *
 * @author  David Mendenhall
 * @author  Alan Kaminsky
 */
public abstract class EnumSyntax implements Serializable, Cloneable {

    private static final long serialVersionUID = -2739521845085831642L;

    /**
     * This enumeration value's integer value.
     * @serial
     */
    private int value;

    /**
     * Construct a new enumeration value with the given integer value.
     *
     * @param  value  Integer value.
     */
    protected EnumSyntax(int value) {
        this.value = value;
    }

    /**
     * Returns this enumeration value's integer value.
     * @return the value
     */
    public int getValue() {
        return value;
    }

    /**
     * Returns a clone of this enumeration value, which to preserve the
     * semantics of enumeration values is the same object as this enumeration
     * value.
     */
    public Object clone() {
        return this;
    }

    /**
     * Returns a hash code value for this enumeration value. The hash code is
     * just this enumeration value's integer value.
     */
    public int hashCode() {
        return value;
    }

    /**
     * Returns a string value corresponding to this enumeration value.
     */
    public String toString() {

        String[] theTable = getStringTable();
        int theIndex = value - getOffset();
        return
            theTable != null && theIndex >= 0 && theIndex < theTable.length ?
            theTable[theIndex] :
            Integer.toString (value);
    }

    /**
     * During object input, convert this deserialized enumeration instance to
     * the proper enumeration value defined in the enumeration attribute class.
     *
     * @return  The enumeration singleton value stored at index
     *          <I>i</I>-<I>L</I> in the enumeration value table returned by
     *          {@link #getEnumValueTable() getEnumValueTable()},
     *          where <I>i</I> is this enumeration value's integer value and
     *          <I>L</I> is the value returned by {@link #getOffset()
     *          getOffset()}.
     *
     * @throws ObjectStreamException if the stream can't be deserialised
     * @throws  InvalidObjectException
     *     Thrown if the enumeration value table is null, this enumeration
     *     value's integer value does not correspond to an element in the
     *     enumeration value table, or the corresponding element in the
     *     enumeration value table is null. (Note: {@link
     *     java.io.InvalidObjectException InvalidObjectException} is a subclass
     *     of {@link java.io.ObjectStreamException ObjectStreamException}, which
     *     <CODE>readResolve()</CODE> is declared to throw.)
     */
    protected Object readResolve() throws ObjectStreamException {

        EnumSyntax[] theTable = getEnumValueTable();

        if (theTable == null) {
            throw new InvalidObjectException(
                                "Null enumeration value table for class " +
                                getClass());
        }

        int theOffset = getOffset();
        int theIndex = value - theOffset;

        if (0 > theIndex || theIndex >= theTable.length) {
            throw new InvalidObjectException
                ("Integer value = " +  value + " not in valid range " +
                 theOffset + ".." + (theOffset + theTable.length - 1) +
                 "for class " + getClass());
        }

        EnumSyntax result = theTable[theIndex];
        if (result == null) {
            throw new InvalidObjectException
                ("No enumeration value for integer value = " +
                 value + "for class " + getClass());
        }
        return result;
    }

    // Hidden operations to be implemented in a subclass.

    /**
     * Returns the string table for this enumeration value's enumeration class.
     * The enumeration class's integer values are assumed to lie in the range
     * <I>L</I>..<I>L</I>+<I>N</I>-1, where <I>L</I> is the value returned by
     * {@link #getOffset() getOffset()} and <I>N</I> is the length
     * of the string table. The element in the string table at index
     * <I>i</I>-<I>L</I> is the value returned by {@link #toString()
     * toString()} for the enumeration value whose integer value
     * is <I>i</I>. If an integer within the above range is not used by any
     * enumeration value, leave the corresponding table element null.
     * <P>
     * The default implementation returns null. If the enumeration class (a
     * subclass of class EnumSyntax) does not override this method to return a
     * non-null string table, and the subclass does not override the {@link
     * #toString() toString()} method, the base class {@link
     * #toString() toString()} method will return just a string
     * representation of this enumeration value's integer value.
     * @return the string table
     */
    protected String[] getStringTable() {
        return null;
    }

    /**
     * Returns the enumeration value table for this enumeration value's
     * enumeration class. The enumeration class's integer values are assumed to
     * lie in the range <I>L</I>..<I>L</I>+<I>N</I>-1, where <I>L</I> is the
     * value returned by {@link #getOffset() getOffset()} and
     * <I>N</I> is the length of the enumeration value table. The element in the
     * enumeration value table at index <I>i</I>-<I>L</I> is the enumeration
     * value object whose integer value is <I>i</I>; the {@link #readResolve()
     * readResolve()} method needs this to preserve singleton
     * semantics during deserialization of an enumeration instance. If an
     * integer within the above range is not used by any enumeration value,
     * leave the corresponding table element null.
     * <P>
     * The default implementation returns null. If the enumeration class (a
     * subclass of class EnumSyntax) does not override this method to return
     * a non-null enumeration value table, and the subclass does not override
     * the {@link #readResolve() readResolve()} method, the base
     * class {@link #readResolve() readResolve()} method will throw
     * an exception whenever an enumeration instance is deserialized from an
     * object input stream.
     * @return the value table
     */
    protected EnumSyntax[] getEnumValueTable() {
        return null;
    }

    /**
     * Returns the lowest integer value used by this enumeration value's
     * enumeration class.
     * <P>
     * The default implementation returns 0. If the enumeration class (a
     * subclass of class EnumSyntax) uses integer values starting at other than
     * 0, override this method in the subclass.
     * @return the offset of the lowest enumeration value.
     */
    protected int getOffset() {
        return 0;
    }

}