001package Torello.Java.Additional;
002
003/**
004 * This simple Generic-Class exists mainly for the case where a function or Type-Parameter needs
005 * to return a class that inherits {@link RetN}, but only has <B STYLE='color:red'>one</B>
006 * return-value.  Outside of that particular scenario, there isn't much point to a {@code Ret1}
007 * instance.
008 * 
009 * <EMBED CLASS=globalDefs DATA-KIND=Ret DATA-N=1>
010 * <EMBED CLASS='external-html' DATA-N=1 DATA-FILE-ID=IMMUTABLE_RET>
011 * @param <A> The type of the <B STYLE='color:red'>only</B> member-field ('{@link #a}').
012 */
013public class Ret1<A>
014    extends RetN
015    implements java.io.Serializable, Cloneable
016{
017    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID>  */
018    protected static final long serialVersionUID = 1;
019
020    /** This holds a pointer the first and only response object. */
021    public final A a;
022
023    /** Constructs this object */
024    public Ret1(A a) { this.a = a; }
025
026    /**
027     * Returns {@code '1'}, indicating how many fields are declared by this class.
028     * @return As an instance of {@code Ret1}, this method returns {@code '1'};
029     */
030    public int n() { return 1; }
031
032    // Super-class uses this for toString, equals, and hashCode
033    // There is an optimization, so if this is requested multiple times, it is saved in a
034    // transient field.
035
036    final Object[] asArrayInternal()
037    { return new Object[] { a }; }
038
039    public Ret1<A> clone()
040    { return new Ret1<>(this.a); }
041
042    /**
043     * Returns this {@code Ret1} instance's only field - field {@link #a}.  This method may only
044     * be invoked on an input value of {@code '1'}, or else it throws.  A {@code Ret1} instance
045     * has only a single field that may be retrieved.
046     * 
047     * <BR /><BR />This method must be included to properly, fully, implement the ancestor 
048     * {@link MultiType} interface.
049     * 
050     * @param i This must be passed {@code '1'}, or else this method throws IOOBEX.
051     * 
052     * @returns The reference contained by field {@link #a}.  If this method returns, its returned
053     * type will always be {@link <A>}.
054     * 
055     * @throws IndexOutOfBoundsException As this {@code Ret1} instance has but a single field,
056     * <I>this exceptions throws for all values of {@code 'i'} - except {@code '1'}</I>.
057     */
058    public A get(final int i)
059    {
060        if (i != 1) throw new IndexOutOfBoundsException(
061            "This is an instance of Ret1, and therefore '1' is the only valid value which may " +
062            "be passed to 'i'"
063        );
064
065        return a;
066    }
067
068    public Tuple1<A> toModifiable()
069    { return new Tuple1<>(this.a); }
070}