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
033    // Super-class uses this for toString, equals, and hashCode
034    // There is an optimization, so if this is requested multiple times, it is saved in a
035    // transient field.
036
037    final Object[] asArrayInternal()
038    { return new Object[] { a }; }
039
040    public Ret1<A> clone()
041    { return new Ret1<>(this.a); }
042
043    /**
044     * Returns this {@code Ret1} instance's only field - field {@link #a}.  This method may only
045     * be invoked on an input value of {@code '1'}, or else it throws.  A {@code Ret1} instance
046     * has only a single field that may be retrieved.
047     * 
048     * <BR /><BR />This method must be included to properly, fully, implement the ancestor 
049     * {@link MultiType} interface.
050     * 
051     * @param i This must be passed {@code '1'}, or else this method throws IOOBEX.
052     * 
053     * @returns The reference contained by field {@link #a}.  If this method returns, its returned
054     * type will always be {@link <A>}.
055     * 
056     * @throws IndexOutOfBoundsException As this {@code Ret1} instance has but a single field,
057     * <I>this exceptions throws for all values of {@code 'i'} - except {@code '1'}</I>.
058     */
059    public A get(final int i)
060    {
061        if (i != 1) throw new IndexOutOfBoundsException(
062            "This is an instance of Ret1, and therefore '1' is the only valid value which may " +
063            "be passed to 'i'"
064        );
065
066        return a;
067    }
068
069    public Tuple1<A> toModifiable()
070    { return new Tuple1<>(this.a); }
071}