Wrapper.java

/*
 Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; version 2 of the License.

 This program 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 for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
*/
/*
 * Wrapper.java
 */

package com.mysql.jtie;

public class Wrapper {

    /*
     * A native function called during static initialization of this class
     * for preloaded caching of field/method Ids.
     *
     * Caution, this leads easily to circular dependencies: If the underlying
     * native library has not been loaded when this function is called, the
     * result is in a non-descriptive UnsatisfiedLinkError.
     *
     * For this, and since preloading cannot be expected to provide a large
     * performance gain, this feature is not implemented at this time.
     *
     * static private native void initIds();
     * static {
     *     initIds();
     * }
     */

    // comments: this field
    // - is allowed to be private, for access from JNI is always possible;
    // - is private for better security and consistency assurances;
    // - must not be final if it is to be nullified when deleting the
    //   native delegate object through this instance from JNI;
    // - is not required to be final under the hashcode() and equals()
    //   consistency requirement;
    // - XXX consider (and benchmark) declaring this field volatile
    //   - a write then happens-before every subsequent read of that field
    //   - writes and reads of volatile longs and doubles are always atomic
    private volatile long cdelegate;

    // comments:
    // - field access from JNI is fast, hence no initialization of this
    //   cdelegate field in a c'tor;
    protected Wrapper() {
        //System.out.println("<-> jtie.Wrapper()");
    };

    protected Wrapper(Wrapper o) {
        //System.out.println("<-> jtie.Wrapper(Wrapper)");
        cdelegate = o.cdelegate;
    };

    // all equals() requirements are met due to pure delegation semantics
    public final boolean equals(Object obj) {
        if (this == obj)
            return true;
        if (!(obj instanceof Wrapper))
            return false;
        final Wrapper wo = (Wrapper)obj;
        return (cdelegate == wo.cdelegate);
    }

    // all hashCode() requirements are met due to pure delegation semantics
    public final int hashCode() {
        return (int)cdelegate; // precision loss ok, for only a hash
    }

    // overrides inherited toString() for full precision of cdelegate
    public String toString() {
        return (getClass().getName() + '@' + Long.toHexString(cdelegate));
    }
}