← Back to branch summary

~ubuntu-branches/ubuntu/trusty/mysql-5.6/trusty

« back to all changes in this revision

Viewing changes to storage/ndb/src/ndbjtie/jtie/com/mysql/jtie/Wrapper.java

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2014-02-12 11:54:27 UTC
  • Revision ID: package-import@ubuntu.com-20140212115427-oq6tfsqxl1wuwehi
Tags: upstream-5.6.15
Import upstream version 5.6.15

Show diffs side-by-side

added added

removed removed

Lines of Context:
storage/ndb/src/ndbjtie/jtie/com/mysql/jtie/Wrapper.java
 
1
/*
 
2
 Copyright (c) 2010, 2012, Oracle and/or its affiliates. All rights reserved.
 
3
 
 
4
 This program is free software; you can redistribute it and/or modify
 
5
 it under the terms of the GNU General Public License as published by
 
6
 the Free Software Foundation; version 2 of the License.
 
7
 
 
8
 This program is distributed in the hope that it will be useful,
 
9
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
 GNU General Public License for more details.
 
12
 
 
13
 You should have received a copy of the GNU General Public License
 
14
 along with this program; if not, write to the Free Software
 
15
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
 
16
*/
 
17
/*
 
18
 * Wrapper.java
 
19
 */
 
20
 
 
21
package com.mysql.jtie;
 
22
 
 
23
/**
 
24
 * A base class for Java peer classes representing a C/C++ object type.
 
25
 *
 
26
 * This class declares only non-public members, which enable the JTie
 
27
 * runtime to map a Java </code>Wrapper</code> instance to a C/C++ object.
 
28
 * 
 
29
 * A Java peer class extending </code>Wrapper</code>
 
30
 * <ol>
 
31
 * <li> must provide a no-arg constructor (may be of any access modifier,
 
32
 *      but preferred private),
 
33
 * <li> will declare a native method for each C/C++ (member and non-member)
 
34
 *      function to be mapped to Java, and
 
35
 * <li> ought not to have any non-static fields (i.e., state by its own).
 
36
 * </ol>
 
37
 *
 
38
 * Please, note that JTie provides no guarantees on the association between
 
39
 * </code>Wrapper</code> instances and their underlying C/C++ objects.
 
40
 * In particular,
 
41
 * <ol>
 
42
 * <li> multiple </code>Wrapper</code> instances may exist for the same
 
43
 *      C/C++ object at any time and
 
44
 * <li> a C/C++ object may have been deleted by the application while
 
45
 *      corresponding Java </code>Wrapper</code> instances still exist
 
46
 *      (i.e., referential integrity cannot be assumed).
 
47
 * </ol>
 
48
 */
 
49
public class Wrapper {
 
50
 
 
51
    /*
 
52
     * A native function called during static initialization of this class
 
53
     * for preloaded caching of field/method Ids.
 
54
     *
 
55
     * Caution, this leads easily to circular dependencies: If the underlying
 
56
     * native library has not been loaded when this function is called, the
 
57
     * result is in a non-descriptive UnsatisfiedLinkError.
 
58
     *
 
59
     * For this, and since preloading cannot be expected to provide a large
 
60
     * performance gain, this feature is not implemented at this time.
 
61
     *
 
62
     * static private native void initIds();
 
63
     * static {
 
64
     *     initIds();
 
65
     * }
 
66
     */
 
67
 
 
68
    /**
 
69
     * The address of the native delegate object.
 
70
     */
 
71
    // comments: this field
 
72
    // - is allowed to be private, for access from JNI is always possible;
 
73
    // - is private for better security and consistency assurances;
 
74
    // - must not be final if it is to be nullified when deleting the
 
75
    //   native delegate object through this instance from JNI;
 
76
    // - is not required to be final under the hashcode() and equals()
 
77
    //   consistency requirement;
 
78
    // - XXX consider (and benchmark) declaring this field volatile
 
79
    //   - a write then happens-before every subsequent read of that field
 
80
    //   - writes and reads of volatile longs and doubles are always atomic
 
81
    private volatile long cdelegate;
 
82
 
 
83
    /**
 
84
     * Creates an unattached wrapper instance.
 
85
     */
 
86
    // comments:
 
87
    // - field access from JNI is fast, hence no initialization of this
 
88
    //   cdelegate field in a c'tor;
 
89
    protected Wrapper() {
 
90
        //System.out.println("<-> jtie.Wrapper()");
 
91
    };
 
92
 
 
93
    /**
 
94
     * Copies a wrapper instance.
 
95
     */
 
96
    protected Wrapper(Wrapper o) {
 
97
        //System.out.println("<-> jtie.Wrapper(Wrapper)");
 
98
        cdelegate = o.cdelegate;
 
99
    };
 
100
 
 
101
    /**
 
102
     * Indicates whether some other object is a wrapper that refers to the
 
103
     * same native delegate instance.
 
104
     * @see Object#equals(Object)
 
105
     */
 
106
    // all equals() requirements are met due to pure delegation semantics
 
107
    public final boolean equals(Object obj) {
 
108
        if (this == obj)
 
109
            return true;
 
110
        if (!(obj instanceof Wrapper))
 
111
            return false;
 
112
        final Wrapper wo = (Wrapper)obj;
 
113
        return (cdelegate == wo.cdelegate);
 
114
    }
 
115
 
 
116
    /**
 
117
     * Returns a hash code value for the object.
 
118
     * @see Object#hashCode()
 
119
     */
 
120
    // all hashCode() requirements are met due to pure delegation semantics
 
121
    public final int hashCode() {
 
122
        return (int)cdelegate; // precision loss ok, for only a hash
 
123
    }
 
124
 
 
125
    /**
 
126
     * Returns a string representation of the object.
 
127
     * @see Object#toString()
 
128
     */
 
129
    // overrides inherited toString() for full precision of cdelegate
 
130
    public String toString() {
 
131
        return (getClass().getName() + '@' + Long.toHexString(cdelegate));
 
132
    }
 
133
}