com.fasterxml.jackson.annotation.JsonProperty Maven / Gradle / Ivy
/*
* Copyright © 2019 Dominokit
*
* 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 com.fasterxml.jackson.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Marker annotation that can be used to define a non-static method as a "setter" or "getter" for a
* logical property (depending on its signature), or non-static object field to be used (serialized,
* deserialized) as a logical property.
*
* Default value ("") indicates that the field name is used as the property name without any
* modifications, but it can be specified to non-empty value to specify different name. Property
* name refers to name used externally, as the field name in JSON objects.
*
*
Starting with Jackson 2.6 this annotation may also be used to change serialization of
* Enum like so:
*
*
* public enum MyEnum {
* {@literal @JsonProperty}("theFirstValue") THE_FIRST_VALUE,
* {@literal @JsonProperty}("another_value") ANOTHER_VALUE;
* }
*
*
* as an alternative to using {@link JsonValue} annotation.
*/
@Target({ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotation
public @interface JsonProperty {
/**
* Special value that indicates that handlers should use the default name (derived from method or
* field name) for property.
*
* @since 2.1
*/
public static final String USE_DEFAULT_NAME = "";
/**
* Marker value used to indicate that no index has been specified. Used as the default value as
* annotations do not allow "missing" values.
*
* @since 2.4
*/
public static final int INDEX_UNKNOWN = -1;
/**
* Defines name of the logical property, i.e. JSON object field name to use for the property. If
* value is empty String (which is the default), will try to use name of the field that is
* annotated. Note that there is no default name available for constructor arguments,
* meaning that Empty String is not a valid value for constructor arguments.
*
* @return String
*/
String value() default USE_DEFAULT_NAME;
/**
* Property that indicates whether a value (which may be explicit null) is expected for property
* during deserialization or not. If expected, BeanDeserialized should indicate this
* as a validity problem (usually by throwing an exception, but this may be sent via problem
* handlers that can try to rectify the problem, for example, by supplying a default value).
*
* Note that as of 2.6, this property is only used for Creator Properties, to ensure existence
* of property value in JSON: for other properties (ones injected using a setter or mutable
* field), no validation is performed. Support for those cases may be added in future. State of
* this property is exposed via introspection, and its value is typically used by Schema
* generators, such as one for JSON Schema.
*
* @since 2.0
* @return boolean
*/
boolean required() default false;
/**
* Property that indicates numerical index of this property (relative to other properties
* specified for the Object). This index is typically used by binary formats, but may also be
* useful for schema languages and other tools.
*
* @since 2.4
* @return int
*/
int index() default INDEX_UNKNOWN;
/**
* Property that may be used to document expected default value for the property: most
* often used as source information for generating schemas (like JSON Schema or protobuf/thrift
* schema), or documentation. It may also be used by Jackson extension modules; core jackson
* databind does not have any automated handling beyond simply exposing this value through bean
* property introspection.
*
*
It is possible that in future this annotation could be used for value defaulting, and
* especially for default values of Creator properties, since they support {@link #required()} in
* 2.6 and above.
*
* @since 2.5
* @return String
*/
String defaultValue() default "";
/**
* Optional property that may be used to change the way visibility of accessors (getter,
* field-as-getter) and mutators (contructor parameter, setter, field-as-setter) is determined,
* either so that otherwise non-visible accessors (like private getters) may be used; or that
* otherwise visible accessors are ignored.
*
*
Default value os {@link Access#AUTO} which means that access is determined solely based on
* visibility and other annotations.
*
* @since 2.6
* @return {@link Access}
*/
Access access() default Access.AUTO;
/**
* Various options for {@link #access} property, specifying how property may be accessed during
* serialization ("read") and deserialization ("write") (note that the direction of read and write
* is from perspective of the property, not from external data format: this may be confusing in
* some contexts).
*
*
Note that while this annotation modifies access to annotated property, its effects may be
* further overridden by {@link JsonIgnore} property: if both annotations are present on an
* accessors, {@link JsonIgnore} has precedence over this property. This annotation property is,
* however, preferred over use of "split" {@link JsonIgnore}/JsonProperty
* combination.
*
* @since 2.6
*/
public enum Access {
/**
* Access setting which means that visibility rules are to be used to automatically determine
* read- and/or write-access of this property.
*/
AUTO,
/**
* Access setting that means that the property may only be read for serialization, but not
* written (set) during deserialization.
*/
READ_ONLY,
/**
* Access setting that means that the property may only be written (set) for deserialization,
* but will not be read (get) on serialization, that is, the value of the property is not
* included in serialization.
*/
WRITE_ONLY,
/**
* Access setting that means that the property will be accessed for both serialization (writing
* out values as external representation) and deserialization (reading values from external
* representation), regardless of visibility rules.
*/
READ_WRITE;
}
}