001package Torello.Java.Additional;
002
003
004/**
005 * Another extremely simple class that can help avoid <CODE>Effectively Final</CODE> Java
006 * Compiler warnings.
007 * 
008 * <EMBED CLASS='external-html' DATA-FILE-ID=LAMBDA_NOTE>
009 * <EMBED CLASS='external-html' DATA-FILE-ID=EFFECTIVE_FINAL>
010 * 
011 * @param <A> Any type.  Class {@code EffectivelyFinal} serves as a wrapper for this type.
012 */
013public class EffectivelyFinal<A> implements Cloneable
014{
015    /**
016     * This variable may be modified inside any Lambda Expression without receiving a compiler
017     * error message.
018     */
019    public A f;
020
021    /**
022     * Creates an instance of this class, and initializes the field.
023     * 
024     * @param f Initializes this class' only field, {@code this.f}, with the value provided by
025     * parameter {@code 'f'}
026     */
027    public EffectivelyFinal(A f) { this.f = f; }
028
029    /**
030     * Creates an instance of this class, and initializes the field {@code this.f} to null.
031     */
032    public EffectivelyFinal()
033    { this.f = null; }
034
035    /**
036     * Invokes the standard {@code java.lang.Object} method {@code toString()} on the field
037     * {@code this.f}.
038     * 
039     * @return Returns the {@code String} produced by the contents' {@code toString()}
040     * */
041    public String toString()
042    { return f.toString(); }
043
044    /**
045     * Invokes the standard {@code java.lang.Object} method {@code hashCode()} on the field
046     * {@code this.f}
047     * 
048     * @return Returns the hash code produced by the contents' {@code hashCode()}.
049     */
050    public int hashCode()
051    { return f.hashCode(); }
052
053    /**
054     * This creates a clone of the wrapper class.
055     * 
056     * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> The field, itself, is not cloned.  Another
057     * {@code EffectivelyFinal} wrapper is built, using the same internal field.  Both the clone
058     * and {@code 'this'} will share a pointer-reference to the same field.
059     * 
060     * @return An {@code EffectivelyFinal<A>} clone.
061     */
062    public EffectivelyFinal<A> clone()
063    { return new EffectivelyFinal<>(f); }
064
065    /**
066     * This equality test checks whether both {@code 'this'} and {@code 'other'} share 
067     * identical references.  Equality between the contained / wrapped field {@code 'f'} is not
068     * checked.
069     * 
070     * <BR /><BR />If {@code this.f} and {@code other.f} hold different references, this method
071     * will return {@code FALSE} <I>even if both of these references have Object-Equality</I>.
072     * 
073     * @return Returns {@code TRUE} if and only if {@code 'other'} is an instance of 
074     * {@code 'EffectivelyFinal'} and {@code this.f == other.f}.  This method checks for
075     * pointer-equality, rather than object-equality.
076     */
077    @SuppressWarnings("rawtypes")
078    public boolean equals(Object other)
079    {
080        if (! (other instanceof EffectivelyFinal)) return false;
081
082        @SuppressWarnings("rawtypes")
083        EffectivelyFinal o = (EffectivelyFinal) other;
084
085        return this.f == o.f;
086    }
087}