Translation Reference

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.
  • 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.
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);