# 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.
  - To rename the generated package prefix see [Package Prefixes](https://developers.google.com/j2objc/guides/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.

##### 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](https://developers.google.com/j2objc/guides/translation-reference#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](https://developers.google.com/j2objc/guides/translation-reference#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);