1 /* 2 * Copyright (C) 2018 Square, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * https://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.squareup.moshi; 17 18 import static java.lang.annotation.RetentionPolicy.RUNTIME; 19 20 import java.lang.annotation.Documented; 21 import java.lang.annotation.Retention; 22 import java.lang.reflect.Type; 23 24 /** Customizes how a type is encoded as JSON. */ 25 @Retention(RUNTIME) 26 @Documented 27 public @interface JsonClass { 28 /** 29 * True to trigger the annotation processor to generate an adapter for this type. 30 * 31 * <p>There are currently some restrictions on which types that can be used with generated 32 * adapters: 33 * 34 * <ul> 35 * <li>The class must be implemented in Kotlin (unless using a custom generator, see {@link 36 * #generator()}). 37 * <li>The class may not be an abstract class, an inner class, or a local class. 38 * <li>All superclasses must be implemented in Kotlin. 39 * <li>All properties must be public, protected, or internal. 40 * <li>All properties must be either non-transient or have a default value. 41 * </ul> 42 */ generateAdapter()43 boolean generateAdapter(); 44 45 /** 46 * An optional custom generator tag used to indicate which generator should be used. If empty, 47 * Moshi's annotation processor will generate an adapter for the annotated type. If not empty, 48 * Moshi's processor will skip it and defer to a custom generator. This can be used to allow other 49 * custom code generation tools to run and still allow Moshi to read their generated JsonAdapter 50 * outputs. 51 * 52 * <p>Requirements for generated adapter class signatures: 53 * 54 * <ul> 55 * <li>The generated adapter must subclass {@link JsonAdapter} and be parameterized by this 56 * type. 57 * <li>{@link Types#generatedJsonAdapterName} should be used for the fully qualified class name 58 * in order for Moshi to correctly resolve and load the generated JsonAdapter. 59 * <li>The first parameter must be a {@link Moshi} instance. 60 * <li>If generic, a second {@link Type Type[]} parameter should be declared to accept type 61 * arguments. 62 * </ul> 63 * 64 * <p>Example for a class "CustomType": 65 * 66 * <pre>{@code 67 * class CustomTypeJsonAdapter(moshi: Moshi, types: Array<Type>) : JsonAdapter<CustomType>() { 68 * // ... 69 * } 70 * }</pre> 71 * 72 * <p>To help ensure your own generator meets requirements above, you can use Moshi’s built-in 73 * generator to create the API signature to get started, then make your own generator match that 74 * expected signature. 75 */ generator()76 String generator() default ""; 77 } 78