Callback


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.swt.internal;
12  
13  
14  /**
15   * Instances of this class represent entry points into Java
16   * which can be invoked from operating system level callback
17   * routines.
18   * <p>
19   * IMPORTANT: A callback is only valid when invoked on the
20   * thread which created it. The results are undefined (and
21   * typically bad) when a callback is passed out to the 
22   * operating system (or other code) in such a way that the
23   * callback is called from a different thread.
24   */
25  
26  public class Callback {
27      
28      Object   object;
29      String   method, signature;
30      int argCount;
31      int /*long*/ address, errorResult;
32      boolean isStatic, isArrayBased;
33  
34      static final String   PTR_SIGNATURE = C.PTR_SIZEOF == 4 ? "I" : "J"; //$NON-NLS-1$  //$NON-NLS-2$
35      static final String   SIGNATURE_0 = getSignature(0);
36      static final String   SIGNATURE_1 = getSignature(1);
37      static final String   SIGNATURE_2 = getSignature(2);
38      static final String   SIGNATURE_3 = getSignature(3);
39      static final String   SIGNATURE_4 = getSignature(4);
40      static final String   SIGNATURE_N = "(["+PTR_SIGNATURE+")"+PTR_SIGNATURE; //$NON-NLS-1$  //$NON-NLS-2$
41  
42  /**
43   * Constructs a new instance of this class given an object
44   * to send the message to, a string naming the method to
45   * invoke and an argument count. Note that, if the object
46   * is an instance of <code>Class</code> it is assumed that
47   * the method is a static method on that class.
48   *
49   * @param object the object to send the message to
50   * @param method the name of the method to invoke
51   * @param argCount the number of arguments that the method takes
52   */
53  public Callback (Object   object, String   method, int argCount) {
54      this (object, method, argCount, false);
55  }
56  
57  /**
58   * Constructs a new instance of this class given an object
59   * to send the message to, a string naming the method to
60   * invoke, an argument count and a flag indicating whether
61   * or not the arguments will be passed in an array. Note 
62   * that, if the object is an instance of <code>Class</code>
63   * it is assumed that the method is a static method on that
64   * class.
65   *
66   * @param object the object to send the message to
67   * @param method the name of the method to invoke
68   * @param argCount the number of arguments that the method takes
69   * @param isArrayBased <code>true</code> if the arguments should be passed in an array and false otherwise
70   */
71  public Callback (Object   object, String   method, int argCount, boolean isArrayBased) {
72      this (object, method, argCount, isArrayBased, 0);
73  }
74  
75  /**
76   * Constructs a new instance of this class given an object
77   * to send the message to, a string naming the method to
78   * invoke, an argument count, a flag indicating whether
79   * or not the arguments will be passed in an array and a value
80   * to return when an exception happens. Note that, if
81   * the object is an instance of <code>Class</code>
82   * it is assumed that the method is a static method on that
83   * class.
84   *
85   * @param object the object to send the message to
86   * @param method the name of the method to invoke
87   * @param argCount the number of arguments that the method takes
88   * @param isArrayBased <code>true</code> if the arguments should be passed in an array and false otherwise
89   * @param errorResult the return value if the java code throws an exception
90   */
91  public Callback (Object   object, String   method, int argCount, boolean isArrayBased, int /*long*/ errorResult) {
92  
93      /* Set the callback fields */
94      this.object = object;
95      this.method = method;
96      this.argCount = argCount;
97      this.isStatic = object instanceof Class  ;
98      this.isArrayBased = isArrayBased;
99      this.errorResult = errorResult;
100     
101     /* Inline the common cases */
102     if (isArrayBased) {
103         signature = SIGNATURE_N;
104     } else {
105         switch (argCount) {
106             case 0: signature = SIGNATURE_0; break; //$NON-NLS-1$
107             case 1: signature = SIGNATURE_1; break; //$NON-NLS-1$
108             case 2: signature = SIGNATURE_2; break; //$NON-NLS-1$
109             case 3: signature = SIGNATURE_3; break; //$NON-NLS-1$
110             case 4: signature = SIGNATURE_4; break; //$NON-NLS-1$
111             default:
112                 signature = getSignature(argCount);
113         }
114     }
115     
116     /* Bind the address */
117     address = bind (this, object, method, signature, argCount, isStatic, isArrayBased, errorResult);
118 }
119 
120 /**
121  * Allocates the native level resources associated with the
122  * callback. This method is only invoked from within the
123  * constructor for the argument.
124  *
125  * @param callback the callback to bind
126  * @param object the callback's object
127  * @param method the callback's method
128  * @param signature the callback's method signature
129  * @param argCount the callback's method argument count
130  * @param isStatic whether the callback's method is static
131  * @param isArrayBased whether the callback's method is array based
132  * @param errorResult the callback's error result
133  */
134 static native synchronized int /*long*/ bind (Callback callback, Object   object, String   method, String   signature, int argCount, boolean isStatic, boolean isArrayBased, int /*long*/ errorResult);
135 
136 /**
137  * Releases the native level resources associated with the callback,
138  * and removes all references between the callback and
139  * other objects. This helps to prevent (bad) application code
140  * from accidentally holding onto extraneous garbage.
141  */
142 public void dispose () {
143     if (object == null) return;
144     unbind (this);
145     object = method = signature = null;
146     address = 0;
147 }
148 
149 /**
150  * Returns the address of a block of machine code which will
151  * invoke the callback represented by the receiver.
152  *
153  * @return the callback address
154  */
155 public int /*long*/ getAddress () {
156     return address;
157 }
158 
159 /**
160  * Returns the SWT platform name.
161  *
162  * @return the platform name of the currently running SWT
163  */
164 public static native String   getPlatform ();
165 
166 /**
167  * Returns the number of times the system has been recursively entered
168  * through a callback.
169  * <p>
170  * Note: This should not be called by application code.
171  * </p>
172  * 
173  * @return the entry count
174  * 
175  * @since 2.1
176  */
177 public static native int getEntryCount ();
178 
179 static String   getSignature(int argCount) {
180     String   signature = "("; //$NON-NLS-1$
181     for (int i = 0; i < argCount; i++) signature += PTR_SIGNATURE;
182     signature += ")" + PTR_SIGNATURE; //$NON-NLS-1$
183     return signature;
184 }
185 
186 /**
187  * Indicates whether or not callbacks which are triggered at the
188  * native level should cause the messages described by the matching
189  * <code>Callback</code> objects to be invoked. This method is used
190  * to safely shut down SWT when it is run within environments
191  * which can generate spurious events.
192  * <p>
193  * Note: This should not be called by application code.
194  * </p>
195  *
196  * @param enable true if callbacks should be invoked
197  */
198 public static final native synchronized void setEnabled (boolean enable);
199 
200 /**
201  * Returns whether or not callbacks which are triggered at the
202  * native level should cause the messages described by the matching
203  * <code>Callback</code> objects to be invoked. This method is used
204  * to safely shut down SWT when it is run within environments
205  * which can generate spurious events.
206  * <p>
207  * Note: This should not be called by application code.
208  * </p>
209  *
210  * @return true if callbacks should not be invoked
211  */
212 public static final native synchronized boolean getEnabled ();
213 
214 /**
215  * This might be called directly from native code in environments
216  * which can generate spurious events. Check before removing it.
217  *
218  * @deprecated
219  *
220  * @param ignore true if callbacks should not be invoked
221  */
222 static final void ignoreCallbacks (boolean ignore) {
223     setEnabled (!ignore);
224 } 
225 
226 /**
227  * Immediately wipes out all native level state associated
228  * with <em>all</em> callbacks.
229  * <p>
230  * <b>WARNING:</b> This operation is <em>extremely</em> dangerous,
231  * and should never be performed by application code.
232  * </p>
233  */
234 public static final native synchronized void reset ();
235 
236 /**
237  * Releases the native level resources associated with the callback.
238  *
239  * @see #dispose
240  */
241 static final native synchronized void unbind (Callback callback);
242 
243 }
244
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags