Java uses packages to informally define namespaces; while Objective C++ has C++ namespaces,
Objective C doesn't. To preserve name uniqueness when using classes from multiple packages,
J2ObjC prepends a camel-cased version of the package to the type name. For example,
java.util.Map is renamed to
Unfortunately, camel-cased package names can reduce readability of the generated code, especially
with long package names. For example, Google Guava's
is in the
com.google.common.annotations package, and
ComGoogleCommonAnnotationsBeta is harder to
Defining a Package Prefix
The Objective-C convention for defining informal namespaces is to use a shared prefix, usually two
uppercase letters. The iOS Foundation Framework uses "NS" (from
NeXTStep), for instance. To simplify Google Guava's Beta
name, a prefix such as "GG" would improve readability by referring to
J2ObjC supports developers specifying their own prefixes to map to package names. This is done on
the command line using
--prefix package=prefix. To shorten all the class names in
Beta's package, the "
--prefix com.google.common.annotations=GG"" would be used. A separate
prefix declaration is needed for each package.
Defining a Single Prefix for Multiple Packages
Smaller libraries often have Java class names that don't conflict, and so can share a single prefix
with a wildcarded package specification. For example, all of the Joda-Time packages can share the same JT prefix, using
'org.joda.time.*=JT'. The only wildcard character supported is '*', which matches the same way the
command-line shell does with filenames.
Defining Multiple Package Prefixes
To simplify specifying several prefix definitions, a properties file can be used with the
--prefixes file" argument:
com.google.common.annotations: GG com.google.common.base: GG # While GG can be used for all packages, let's mix it up. com.google.common.collect: GC com.google.common.io: GIO # A prefix can be more than two characters, com.google.common.net: GuavaNet # a lot more! ...
j2objc --prefixes prefixes.properties <args>
Prefixed Classes at Runtime
Since the finished app has classes with prefixes, they cannot be located using the original Java
class name by default. However, if the app has a file named prefixes.properties in its resource
bundle with the prefixes used for translation,
Class.forName(javaName) will find the mapped class.
To add the above prefixes.properties to an iOS app in Xcode, open the build target's Build Phases tab, expand its Copy Bundle Resources section, and add the prefixes.properties file to that list. Java Resources has further information on how Java resource concepts map to iOS resources.