ca.weblite.objc
Class RuntimeUtils

java.lang.Object
  ca.weblite.objc.RuntimeUtils

public class RuntimeUtils
extends Object

A Java class with static methods that interact with the Objective-C runtime. These methods wrap the *very* low level methods provided by the Runtime class to provide a slightly higher level of abstraction.

It is helpful to perform a static import of the methods in this class if you will be using the objc runtime library, as it contains many utility methods to deal with Objective-C primitives. E.g. the cls() method can return the Pointer to a class given its name. The clsName() returns the name of the class specified by a Pointer().

There are also many variants of the msg() method for sendng messages to objects in the Objective-C runtime.

Author:

shannah

See Also:

Objective-C Runtime Reference

Field Summary

static boolean	loaded Flag to indicate whether the jcocoa native library was loaded successfully.
static Runtime	rt Short reference to the runtime instance for interacting with Objective-C

Constructor Summary

RuntimeUtils()

Method Summary

static com.sun.jna.Pointer	addr(Peerable peer) Returns the pointer to the Native peer for a Peerable object.
static int	arraySize(String signature) Returns the size of an array that is specified in a signature.
static com.sun.jna.Pointer	cls(Peerable peer) Returns a pointer to a class given a Peerable object which wraps the pointer.
static com.sun.jna.Pointer	cls(String name) Returns a pointer to the class for specific class name.
static String	clsName(Peerable peer) A wrapper for the clsName() method given a Peerable object that wraps the class pointer.
static String	clsName(com.sun.jna.Pointer cls) Returns the name of an objective C class specified by the given class pointer.
static long	createProxy(Recipient client) Registers a Java object with the Objective-C runtime so that it can begin to receive messages from it.
static com.sun.jna.Pointer	getAsReference(Object val, String signature) Wraps the given value in the appropriate ByReference subclass according to the provided signature.
static com.sun.jna.ptr.ByReference	getAsReferenceWrapper(Object val, String signature) Wraps the given value in the appropriate ByReference subclass according to the provided signature.
static Recipient	getJavaPeer(long nsObject) Returns the Java peer recipient for a native Objective-C object if it exists.
static void	init() Initializes the libjcocoa library.
static Object	msg(boolean coerceReturn, boolean coerceArgs, com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Sends a message with the option of coercing the inputs and outputs.
static Object	msg(Message... messages) Sends a batch of messages in sequence.
static long	msg(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Sends a message to a specified class using the given selector.
static long	msg(com.sun.jna.Pointer receiver, String msg, Object... args) Sends a message to a specified class using the given selector.
static long	msg(String cls, com.sun.jna.Pointer msg, Object... args) Sends a message to a specified class using the given selector.
static long	msg(String cls, String msg, Object... args) Sends a message to a specified class using the given selector.
static boolean	msgBoolean(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns a boolean value.
static boolean	msgBoolean(com.sun.jna.Pointer receiver, String selector, Object... args) Wrapper around msg() that returns a boolean value.
static boolean	msgBoolean(String receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns a boolean value.
static boolean	msgBoolean(String receiver, String selector, Object... args) Wrapper around msg() that returns a boolean value.
static double	msgDouble(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Sends a message that returns a double value.
static double	msgDouble(com.sun.jna.Pointer receiver, String selector, Object... args) Sends a message that returns a double value.
static double	msgDouble(String receiver, com.sun.jna.Pointer selector, Object... args) Sends a message that returns a double value.
static double	msgDouble(String receiver, String selector, Object... args) Sends a message that returns a double value.
static int	msgInt(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns an int.
static int	msgInt(com.sun.jna.Pointer receiver, String selector, Object... args) Wrapper around msg() that returns an int.
static int	msgInt(String receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns an int.
static int	msgInt(String receiver, String selector, Object... args) Wrapper around msg() that returns an int.
static com.sun.jna.Pointer	msgPointer(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns a Pointer.
static com.sun.jna.Pointer	msgPointer(com.sun.jna.Pointer receiver, String selector, Object... args) Wrapper around msg() that returns a Pointer.
static com.sun.jna.Pointer	msgPointer(String receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns a Pointer.
static com.sun.jna.Pointer	msgPointer(String receiver, String selector, Object... args) Wrapper around msg() that returns a Pointer.
static String	msgString(com.sun.jna.Pointer receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns a string value.
static String	msgString(com.sun.jna.Pointer receiver, String selector, Object... args) Wrapper around msg() that returns a string value.
static String	msgString(String receiver, com.sun.jna.Pointer selector, Object... args) Wrapper around msg() that returns a string value.
static String	msgString(String receiver, String selector, Object... args) Wrapper around msg() that returns a string value.
static com.sun.jna.Pointer	sel(Peerable peer) Returns a pointer to the selector that is wrapped by a Peerable object.
static com.sun.jna.Pointer	sel(String name) Returns a pointer to the selector specified by the given selector name.
static String	selName(Peerable peer) Returns the name of a selector.
static String	selName(com.sun.jna.Pointer sel) Returns the name of a selector.
static String	str(com.sun.jna.Pointer str) Converts A native NSString object to a Java string.
static com.sun.jna.Pointer	str(String str) Converts a Java string to an NSString object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

rt

public static Runtime rt

Short reference to the runtime instance for interacting with Objective-C

loaded

public static boolean loaded

Flag to indicate whether the jcocoa native library was loaded successfully. If it fails to load, then this flag will be false. Therefore, if this flag is false, you shouldn't try to use the the api at all.

Constructor Detail

RuntimeUtils

public RuntimeUtils()

Method Detail

cls

public static com.sun.jna.Pointer cls(String name)

Returns a pointer to the class for specific class name.

 Pointer nsObject = cls("NSObject");
 

Parameters:

name - The name of the class to retrieve.

Returns:

The pointer to the class structure.

cls

public static com.sun.jna.Pointer cls(Peerable peer)

Returns a pointer to a class given a Peerable object which wraps the pointer. Effectively this just calls peer.getPeer() and returns its value. A convenience method.

Parameters:

peer - The peer object that is wrapping the Objective-C class object.

Returns:

A Pointer to the Objective-C class.

clsName

public static String clsName(com.sun.jna.Pointer cls)

Returns the name of an objective C class specified by the given class pointer.

Parameters:

cls - The pointer to the class whose name we wish to retrieve.

Returns:

The name of the class.

See Also:

Runtime.class_getName()

clsName

public static String clsName(Peerable peer)

A wrapper for the clsName() method given a Peerable object that wraps the class pointer. This will return the class name.

Parameters:

peer -

Returns:

The class name of the objective-c class that is wrapped by the given Peerable object.

See Also:

Runtime.class_getName()

sel

public static com.sun.jna.Pointer sel(String name)

Returns a pointer to the selector specified by the given selector name.

Parameters:

name -

Returns:

Pointer to an Objective-C message selector.

See Also:

Objective-C Selectors Reference

sel

public static com.sun.jna.Pointer sel(Peerable peer)

Returns a pointer to the selector that is wrapped by a Peerable object.

Parameters:

peer -

Returns:

Pointer to a specified selector.

selName

public static String selName(com.sun.jna.Pointer sel)

Returns the name of a selector.

Parameters:

sel - Pointer to a selector.

Returns:

The name of the selector.

selName

public static String selName(Peerable peer)

Returns the name of a selector.

Parameters:

sel - Peerable that wraps a pointer to a selector.

Returns:

The name of the selector.

msg

public static long msg(String cls,
                       String msg,
                       Object... args)

Sends a message to a specified class using the given selector.

Parameters:

cls - The name of the class.

msg - The name of the selector.

args - The arguments passed to the method. These are passed raw and will not be coerced.

Returns:

The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.

See Also:

msgDouble()

msg

public static long msg(String cls,
                       com.sun.jna.Pointer msg,
                       Object... args)

Sends a message to a specified class using the given selector.

Parameters:

cls - The name of the class.

msg - The name of the selector.

args - The arguments passed to the method. These are passed raw and will not be coerced.

Returns:

The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.

See Also:

msgDouble()

msg

public static long msg(com.sun.jna.Pointer receiver,
                       String msg,
                       Object... args)

Sends a message to a specified class using the given selector.

Parameters:

cls - The name of the class.

msg - The name of the selector.

args - The arguments passed to the method. These are passed raw and will not be coerced.

Returns:

The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.

See Also:

msgDouble()

msg

public static long msg(com.sun.jna.Pointer receiver,
                       com.sun.jna.Pointer selector,
                       Object... args)

Sends a message to a specified class using the given selector.

Parameters:

cls - The name of the class.

msg - The name of the selector.

args - The arguments passed to the method. These are passed raw and will not be coerced.

Returns:

The result of the message. This may be a pointer, if the message returns a pointer, or a value, if the method returns a BOOL, long, int, short, byte, or char. Note that you cannot use this method for messages that return float and double values. For these, you must use msgDouble(). This is because doubles and floats are handled using a different underlying runtime function (objc_msgSend_fpret). Alternatively you can use the variation of msg() that takes coerceInput and coerceOutput boolean values, as this will automatically choose the correct underlying message function depending on the return type reported by the message signature.

See Also:

msgDouble()

msgPointer

public static com.sun.jna.Pointer msgPointer(com.sun.jna.Pointer receiver,
                                             com.sun.jna.Pointer selector,
                                             Object... args)

Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

A Pointer return value of the message.

msgPointer

public static com.sun.jna.Pointer msgPointer(com.sun.jna.Pointer receiver,
                                             String selector,
                                             Object... args)

Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

A Pointer return value of the message.

msgPointer

public static com.sun.jna.Pointer msgPointer(String receiver,
                                             com.sun.jna.Pointer selector,
                                             Object... args)

Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

A Pointer return value of the message.

msgPointer

public static com.sun.jna.Pointer msgPointer(String receiver,
                                             String selector,
                                             Object... args)

Wrapper around msg() that returns a Pointer. This should only be used for sending messages that return Pointers (or Objects).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

A Pointer return value of the message.

msgInt

public static int msgInt(com.sun.jna.Pointer receiver,
                         com.sun.jna.Pointer selector,
                         Object... args)

Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

An int value returned by the message.

msgInt

public static int msgInt(String receiver,
                         com.sun.jna.Pointer selector,
                         Object... args)

Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

An int value returned by the message.

msgInt

public static int msgInt(String receiver,
                         String selector,
                         Object... args)

Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

An int value returned by the message.

msgInt

public static int msgInt(com.sun.jna.Pointer receiver,
                         String selector,
                         Object... args)

Wrapper around msg() that returns an int. This should only be used for sending messages that return int-compatible numeric values. E.g. byte, bool, long, int, short. Do not use this if the message will return something else (like a float, double, string, or pointer).

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

An int value returned by the message.

msgBoolean

public static boolean msgBoolean(com.sun.jna.Pointer receiver,
                                 com.sun.jna.Pointer selector,
                                 Object... args)

Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

Boolean return value of the message.

msgBoolean

public static boolean msgBoolean(String receiver,
                                 com.sun.jna.Pointer selector,
                                 Object... args)

Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

Boolean return value of the message.

msgBoolean

public static boolean msgBoolean(String receiver,
                                 String selector,
                                 Object... args)

Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

Boolean return value of the message.

msgBoolean

public static boolean msgBoolean(com.sun.jna.Pointer receiver,
                                 String selector,
                                 Object... args)

Wrapper around msg() that returns a boolean value. This should only be used for sending messages that return boolean-compatible numeric values. Essentially any non-zero value is interpreted (and returned) as true. Zero values are interpreted as false.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

Boolean return value of the message.

msgString

public static String msgString(com.sun.jna.Pointer receiver,
                               com.sun.jna.Pointer selector,
                               Object... args)

Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

The string return value of the message.

msgString

public static String msgString(String receiver,
                               com.sun.jna.Pointer selector,
                               Object... args)

Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

The string return value of the message.

msgString

public static String msgString(String receiver,
                               String selector,
                               Object... args)

Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

The string return value of the message.

msgString

public static String msgString(com.sun.jna.Pointer receiver,
                               String selector,
                               Object... args)

Wrapper around msg() that returns a string value. This should only be used for messages that return a CString. Do not use this for messages that return numeric values or Pointers to objects (e.g. NSString). Use the msg() variant that takes coerceInputs and coerceOutputs parameters if you want NSStrings to be automatically converted to java Strings.

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - Arguments passed to the message.

Returns:

The string return value of the message.

msgDouble

public static double msgDouble(com.sun.jna.Pointer receiver,
                               com.sun.jna.Pointer selector,
                               Object... args)

Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

The double return value of the message

msgDouble

public static double msgDouble(String receiver,
                               com.sun.jna.Pointer selector,
                               Object... args)

Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

The double return value of the message

msgDouble

public static double msgDouble(String receiver,
                               String selector,
                               Object... args)

Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

The double return value of the message

msgDouble

public static double msgDouble(com.sun.jna.Pointer receiver,
                               String selector,
                               Object... args)

Sends a message that returns a double value. This variant must be used if the method returns a float or a double. It doesn't actually wrap the primitive msg() method.. Rather it uses a different core Objective-C method, objc_msgSend_fpret().

Parameters:

receiver - The target of the message.

selector - The selector for the message.

args - The arguments passed to the message.

Returns:

The double return value of the message

msg

public static Object msg(boolean coerceReturn,
                         boolean coerceArgs,
                         com.sun.jna.Pointer receiver,
                         com.sun.jna.Pointer selector,
                         Object... args)

Sends a message with the option of coercing the inputs and outputs. This variant uses a higher level of abstraction than the standard msg() and msgXXX() methods. If coerceReturn and coerceArgs are set to true, then this method will convert the inputs from Java inputs to the corresponding Objective-C inputs. Further it will return values that are more appropriate for use in Java.

Furthermore, this variant is smart about which variable of msg() to call behind the scenes. E.g. if the message signature specifies that this message returns a double, it will automatically use the double variant of msg().

Parameters:

coerceReturn - If true, then the return value will be mapped to an appropriate Java value using the TypeMapper class.

coerceArgs - If true, then the inputs will be mapped from Java to appropriate C values using the TypeMapper class.

receiver - The target of the message.

selector - The selector for the message.

args - The arguments to be passed in the message.

Returns:

The return value of the message. This may be a Pointer or a value depending on the return type of the message.

arraySize

public static int arraySize(String signature)

Returns the size of an array that is specified in a signature.

Parameters:

signature - The signature for a parameter using Objective-C type encodings.

Returns:

The size of the array.

See Also:

Objective-C Type Encodings

addr

public static com.sun.jna.Pointer addr(Peerable peer)

Returns the pointer to the Native peer for a Peerable object.

Parameters:

peer -

Returns:

The Pointer to a native peer.

msg

public static Object msg(Message... messages)

Sends a batch of messages in sequence.

Parameters:

messages -

Returns:

The result of the last message sent. The results of the individual messages will also be stored inside the message objects themselves.

str

public static com.sun.jna.Pointer str(String str)

Converts a Java string to an NSString object.

Parameters:

str - The Java string to convert.

Returns:

Pointer to the NSString that corresponds to this string.

str

public static String str(com.sun.jna.Pointer str)

Converts A native NSString object to a Java string.

Parameters:

str -

Returns:

A Java string.

getAsReference

public static com.sun.jna.Pointer getAsReference(Object val,
                                                 String signature)

Wraps the given value in the appropriate ByReference subclass according to the provided signature. This is a useful method in cases where you need to pass a parameter to a C-function by reference, but you don't necessarily know what type of data it is.

Parameters:

val - The value to be wrapped in a byReference.

signature - The signature (using Objective-C type encodings) of the value.

Returns:

A pointer to the reference that can be passed in a C function.

See Also:

Objective-C Type Encodings

getAsReferenceWrapper

public static com.sun.jna.ptr.ByReference getAsReferenceWrapper(Object val,
                                                                String signature)

Wraps the given value in the appropriate ByReference subclass according to the provided signature. This is a useful method in cases where you need to pass a parameter to a C-function by reference, but you don't necessarily know what type of data it is.

Parameters:

val - The value to be wrapped in a byReference.

signature - The signature (using Objective-C type encodings) of the value.

Returns:

The ByReference object that contains the pointer that can be passed to a c function.

See Also:

Objective-C Type Encodings

init

public static void init()

Initializes the libjcocoa library. This is called when the class is first loaded. It sets up the JNI environment that will be used there forward.

createProxy

public static long createProxy(Recipient client)

Registers a Java object with the Objective-C runtime so that it can begin to receive messages from it. This will create an Objective-C proxy that passes messages to the Recipient object. This step is automatically handled by the NSObject class inside its init() method.

Parameters:

client -

Returns:

getJavaPeer

public static Recipient getJavaPeer(long nsObject)

Returns the Java peer recipient for a native Objective-C object if it exists. This will return null if nsObject is not an WLProxy object that has been previously registered with a Recipient.

Parameters:

nsObject -

Returns: