Types
- For primitive types, J2ObjC has defined JNI-style typedefs.
- For typical class types, the package is camel-cased and prepended to the class name.
- To rename the generated package prefix see Package Prefixes.
- For the base Object type and all type variables, "id" is used.
- A few core Java types are mapped to foundation types. (eg. String to NSString)
- For fields declared 'volatile', J2ObjC has more typedefs that use C11 _Atomic(...) types.
- For inner types the inner class name is appended to the outer name with an underscore.
Java type | Objective-C type | Objective-C volatile type |
---|---|---|
boolean | jboolean | volatile_jboolean |
char | jchar | volatile_jchar |
byte | jbyte | volatile_jbyte |
short | jshort | volatile_jshort |
int | jint | volatile_jint |
long | jlong | volatile_jlong |
float | jfloat | volatile_jfloat |
double | jdouble | volatile_jdouble |
java.lang.Object | id | volatile_id |
type variables | id | volatile_id |
java.lang.String | NSString* | volatile_id |
java.lang.Number | NSNumber* | volatile_id |
java.lang.Cloneable | NSCopying* | volatile_id |
foo.bar.Mumble | FooBarMumble* | volatile_id |
foo.bar.Mumber$Inner | FooBarMumble_Inner* | volatile_id |
Methods
Objective-C methods differ from Java methods in two important ways. They are syntactically different, embedding the parameters in between components of the method selector. Objective-C methods don't support overloading like Java does. These differences are resolved by embedding the parameter types into the generated selector. This is necessary to prevent name collisions between overloaded Java methods.
There are three kinds of Java methods that differ in their generated API: instance methods, static methods, and constructors. Instance methods translate into Objective-C instance methods. Static methods and constructors translate into C-style functions, but also add Objective-C wrappers to provide a more familiar API to Objective-C developers.
Instance Methods
Method names are generated as follows:
- Zero parameter methods are unchanged
- One or more parameter uses the following pattern:
<java name>With<1st param keyword>:with<2nd param keyword>:with<3rd param keyword>:
- Parameter keyword rules:
- For primitive types, the keyword is the capitalized name of the Java primitive. (eg. "Char")
- For non-primitive types, the keyword is the camel-cased fully qualified type name. (eg. "ComGoogleFoo")
- For array types, "Array" is appended to the keyword of the element type.
Example Java
interface Foo {
void bar();
String bar(int i);
java.util.List bar(String s, long[] l);
}
Example Objective-C
- (void)bar;
- (NSString *)barWithInt:(jint)i;
- (id<JavaUtilList>)barWithNSString:(NSString *)s
withLongArray:(IOSLongArray *)l;
Static Methods
An Objective-C class method is added following the same naming rules as instance methods.
A C-style function is added using the following naming rules:
- Start with the generated Objective-C selector. (eg.
barWithInt:
) - Replace colons with underscores. (eg.
barWithInt_
) - Prepend the class name, delimited with an underscore. (eg.
ComGoogleFoo_barWithInt_
)
Example Java
package com.google;
class Foo {
static boolean bar() { ... }
static double bar(int[] i) { ... }
static void bar(String s, boolean b) { ... }
}
Example Objective-C
@interface Foo : NSObject
+ (jboolean)bar;
+ (jdouble)barWithIntArray:(IOSIntArray *)i;
+ (void)barWithNSString:(NSString *)s
withBoolean:(jboolean)b;
@end
FOUNDATION_EXPORT jboolean ComGoogleFoo_bar();
FOUNDATION_EXPORT jdouble ComGoogleFoo_barWithIntArray_(IOSIntArray *i);
FOUNDATION_EXPORT void ComGoogleFoo_barWithNSString_withBoolean_(NSString *s, jboolean b);
Constructors
Following the Objective-C convention, an init
instance method is added. If the constructor has
parameters, the same naming rule as instance methods is used.
Three C-style functions are added:
- The first function accepts a newly allocated object as its first parameter. This function is typically used for calling from a subclass constructor. This follows the same naming rules as static methods. (where "init" is the method name)
- Two functions are added that will allocate and initialize the new object. They are distinguished
by their prefix:
- The
create_
function will return an autoreleased object. - The
new_
function will return a retained object.
- The
Example Java
package com.google;
class Foo {
Foo() { ... }
Foo(Object a, Object b) { ... }
}
Example Objective-C
@interface ComGoogleFoo : NSObject
- (instancetype)init;
- (instancetype)initWithId:(id)a
withId:(id)b;
@end
FOUNDATION_EXPORT void ComGoogleFoo_init(ComGoogleFoo *self);
FOUNDATION_EXPORT ComGoogleFoo *new_ComGoogleFoo_init() NS_RETURNS_RETAINED;
FOUNDATION_EXPORT ComGoogleFoo *create_ComGoogleFoo_init();
FOUNDATION_EXPORT void ComGoogleFoo_initWithId_withId_(ComGoogleFoo *self, id a, id b);
FOUNDATION_EXPORT ComGoogleFoo *new_ComGoogleFoo_initWithId_withId_(id a, id b) NS_RETURNS_RETAINED;
FOUNDATION_EXPORT ComGoogleFoo *create_ComGoogleFoo_initWithId_withId_(id a, id b);
Fields
Instance Fields (non-static)
Java instance variables become Objective-C instance variables. The name is the same with a trailing underscore. Primitive fields declared "final" are a special case and are not translated to instance variables.
- Fields can be accessed directly using "->" syntax.
- Primitive fields can be set directly.
- Final primitives (constants) are translated like static constants. (see Static Fields)
- Non-primitive fields must be set using the provided setter function:
ClassName_set_fieldName_(instance, value)
Example Java
package com.google;
class Foo {
public int myInt;
public String myString;
}
Example Objective-C
Foo *foo = [[Foo alloc] init];
// Access a primitive field.
i = foo->myInt_;
// Set a primitive field.
foo->myInt_ = 5;
// Access a non-primitive field.
NSString *s = foo->myString_;
// Set a non-primitive field.
ComGoogleFoo_set_myString_(foo, @"bar");
Static Fields
Static variables must be accessed using the provided getter and setter functions. These accessor functions ensure that class initialization has occurred prior to accessing the variable.
- Access a static field
ClassName_get_fieldName()
- Assign a (non-final) static field
ClassName_set_fieldName()
- Get a pointer to a primitive static field
ClassName_getRef_fieldName()
- Only available for non-final and non-volatile fields.
Final primitive fields (constants) are safe to access directly because their value does not depend on class initialization.
ClassName_fieldName
Example Java
package com.google;
class Foo {
public static final MY_FINAL_INT = 5;
public static int myInt;
public static String myString;
}
Example Objective-C
// Access a primitive constant field.
jint i = ComGoogleFoo_MY_FINAL_INT; // No class initialization
i = ComGoogleFoo_get_MY_FINAL_INT(); // Class initialization
// Access a primitive field.
i = ComGoogleFoo_get_myInt();
// Set a primitive field.
ComGoogleFoo_set_myInt(5);
// Access a non-primitive field.
NSString *s = ComGoogleFoo_get_myString();
// Set a non-primitive field.
ComGoogleFoo_set_myString(@"bar");
Enums
J2ObjC generates two types for each Java enum. An Objective-C class type is generated which provides the full functionality of a Java enum. Additionally a C enum is generated using the Foundation framework's NS_ENUM macro. The Objective-C class type is used by all generated API. The C enum is useful as constant values for a switch statement, or as a storage type.
The generated enum types are named as follows:
- The Objective-C class is named using the same rule as a regular Java class. (see Types)
- The C enum is named as a regular Java class with an added "_Enum" suffix.
Enum constants are accessed like static fields.
Example Java
package com.google;
enum Color {
RED, GREEN, BLUE
}
Example Objective-C Header
typedef NS_ENUM(NSUInteger, ComGoogleColor_Enum) {
ComGoogleColor_Enum_RED = 0;
ComGoogleColor_Enum_GREEN = 1;
ComGoogleColor_Enum_BLUE = 2;
};
@interface ComGoogleColor : JavaLangEnum < NSCopying >
+ (IOSObjectArray *)values;
+ (ComGoogleColor *)valueOfWithNSString:(NSString *)name;
@end
inline ComGoogleColor *ComGoogleColor_get_RED();
inline ComGoogleColor *ComGoogleColor_get_GREEN();
inline ComGoogleColor *ComGoogleColor_get_BLUE();
// Provides conversion from ComGoogleColor_Enum values.
FOUNDATION_EXPORT ComGoogleColor *ComGoogleColor_fromOrdinal(NSUInteger ordinal);