/* * Copyright 2015 Realm Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package io.realm.annotations; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * By default a Realm can store all classes extending RealmObject in a project. However, if you want to restrict a * Realm to only contain a subset of classes or want to share them between a library project and an app project, you must * use a RealmModule. * <p> * A RealmModule is a collection of classes extending RealmObject that can be combined with other RealmModules to create * the schema for a Realm. This makes it easier to control versioning and migration of those Realms. * <p> * A RealmModule can either be a library module or an app module. The distinction is made by setting * {@code library = true}. Setting {@code library = true} is normally only relevant for library authors. See below for * further details. * * <p> * Currently, it is not possible to have multiple RealmModule declarations in a single file. If you have more than one * RealmModule, you will have to use separate Java files for each module. * * * <h2>RealmModules and libraries</h2> * * Realms default behavior is to automatically create a RealmModule called {@code DefaultRealmModule} which contains all * classes extending RealmObject in a project. This module is automatically known by Realm. * <p> * This behavior is problematic when combining a library project and an app project that both uses Realm. This is * because the {@code DefaultRealmModule} will be created for both the library project and the app project, which will * cause the project to fail with duplicate class definition errors. * <p> * Library authors are responsible for avoiding this conflict by using explicit modules where {@code library = true} is * set. This disables the generation of the DefaultRealmModule for the library project and allows the library to be * included in the app project that also uses Realm. This means that library projects that uses Realm internally are * required to specify a specific module using {@code RealmConfiguration.modules()}. * <p> * App developers are not required to specify any modules, as they implicitly use the {@code DefaultRealmModule}, but * they now has the option of adding the library project classes to their schema using * {@code RealmConfiguration.addModule()}. * * @see <a href="https://github.com/realm/realm-java/tree/master/examples/realmModuleAppExample">Example of a project using modules</a> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) @Inherited public @interface RealmModule { /** * Setting this to true will mark this module as a library module. This will prevent Realm from generating the * {@code DefaultRealmModule} containing all classes. This is required by libraries so they do not interfere with * Realms running in app code, but it also means that all libraries using Realm must explicitly use a module and * cannot rely on the default module being present. * * Creating library modules and normal modules in the same project is not allowed and will result in the annotation * processor throwing an exception. */ boolean library() default false; /** * Instead of adding all Realm classes manually to a module, set this boolean to true to automatically include all * Realm classes in this project. This does not include classes from other libraries which must be exposed using * their own module. * * Setting both {@code allClasses = true} and {@code classes()} will result in the annotation processor throwing * an exception. */ boolean allClasses() default false; /** * Specifies the classes extending RealmObject that should be part of this module. Only classes in this project can * be included. Classes from other libraries must be exposed using their own module. * * Setting both {@code allClasses = true} and {@code classes()} will result in the annotation processor throwing * an exception. */ Class<?>[] classes() default {}; }