org.apache.juneau.annotation.Bean Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you 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 org.apache.juneau.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.beans.*;
import java.lang.annotation.*;
import org.apache.juneau.*;
import org.apache.juneau.transform.*;
/**
* Used to tailor how beans get interpreted by the framework.
*
*
* This annotation can be applied to classes and interfaces.
*
*
See Also:
*
* - {@doc juneau-marshall.Transforms.BeanAnnotation}
*
*/
@Documented
@Target(TYPE)
@Retention(RUNTIME)
@Inherited
public @interface Bean {
/**
* Bean dictionary.
*
*
* The list of classes that make up the bean dictionary for all properties in this class and all subclasses.
*
*
See Also:
*
* - {@link BeanContext#BEAN_beanDictionary}
*
*/
Class[] beanDictionary() default {};
/**
* Specifies a list of properties that should be excluded from {@link BeanMap#entrySet()}.
*
* Example:
*
* // Exclude the 'city' and 'state' properties from the Address class.
* @Bean (excludeProperties="city,state" })
* public class Address {...}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_excludeProperties}
*
*/
String excludeProperties() default "";
/**
* Find fluent setters.
*
*
* When true , fluent setters will be detected on beans.
*
*
* Fluent setters
*
*
Example:
*
* @Bean (fluentSetters=true )
* public class MyBean {
* public int getId() {...}
* public MyBean id(int id) {...}
* }
*
*
*
* Fluent setters must have the following attributes:
*
* - Public.
*
- Not static.
*
- Take in one parameter.
*
- Return the bean itself.
*
*
* See Also:
*
* - {@link BeanContext#BEAN_fluentSetters}
*
*/
boolean fluentSetters() default false;
/**
* Identifies a class to be used as the interface class for this and all subclasses.
*
*
* When specified, only the list of properties defined on the interface class will be used during serialization.
* Additional properties on subclasses will be ignored.
*
*
* // Parent class
* @Bean (interfaceClass=A.class )
* public abstract class A {
* public String f0 = "f0" ;
* }
*
* // Sub class
* public class A1 extends A {
* public String f1 = "f1" ;
* }
*
* // Produces "{f0:'f0'}"
* String json = SimpleJsonSerializer.DEFAULT .serialize(new A1());
*
*
*
* Note that this annotation can be used on the parent class so that it filters to all child classes,
* or can be set individually on the child classes.
*
*
See Also:
*
* - {@link BeanContext#BEAN_beanFilters}
*
*/
Class interfaceClass() default Object.class;
/**
* The set and order of names of properties associated with a bean class.
*
*
* The order specified is the same order that the entries will be returned by the {@link BeanMap#entrySet()} and
* related methods.
*
*
* This value is entirely optional if you simply want to expose all the getters and public fields on
* a class as bean properties.
*
However, it's useful if you want certain getters to be ignored or you want the properties to be
* serialized in a particular order.
*
Note that on IBM JREs, the property order is the same as the order in the source code,
* whereas on Oracle JREs, the order is entirely random.
*
*
Example:
*
* // Address class with only street/city/state properties (in that order).
* @Bean (properties="street,city,state" )
* public class Address {...}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_includeProperties}
*
*/
String properties() default "";
/**
* Property filter.
*
*
* Property filters can be used to intercept calls to getters and setters and alter their values in transit.
*
*
See Also:
*
* - {@link PropertyFilter}
*
*/
Class propertyFilter() default PropertyFilter.class;
/**
* Associates a {@link PropertyNamer} with this bean to tailor the names of the bean properties.
*
*
* Property namers are used to transform bean property names from standard form to some other form.
*
*
Example:
*
* // Define a class with dashed-lowercase property names.
* @Bean (propertyNamer=PropertyNamerDashedLC.class )
* public class MyBean {...}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_propertyNamer}
*
*/
Class propertyNamer() default PropertyNamerDefault.class;
/**
* Sort bean properties in alphabetical order.
*
*
* When true , all bean properties will be serialized and access in alphabetical order.
*
Otherwise, the natural order of the bean properties is used which is dependent on the JVM vendor.
*
*
Example:
*
* // Sort bean properties alphabetically during serialization.
* @Bean (sort=true )
* public class MyBean {...}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_sortProperties}
*
*/
boolean sort() default false;
/**
* Identifies a stop class for the annotated class.
*
*
* Identical in purpose to the stop class specified by {@link Introspector#getBeanInfo(Class, Class)}.
* Any properties in the stop class or in its base classes will be ignored during analysis.
*
*
* For example, in the following class hierarchy, instances of C3 will include property p3,
* but not p1 or p2.
*
* public class C1 {
* public int getP1();
* }
*
* public class C2 extends C1 {
* public int getP2();
* }
*
* @Bean (stopClass=C2.class )
* public class C3 extends C2 {
* public int getP3();
* }
*
*/
Class stopClass() default Object.class;
/**
* An identifying name for this class.
*
*
* The name is used to identify the class type during parsing when it cannot be inferred through reflection.
*
For example, if a bean property is of type Object, then the serializer will add the name to the
* output so that the class can be determined during parsing.
*
*
* It is also used to specify element names in XML.
*
*
Example:
*
* // Use _type='mybean' to identify this bean.
* @Bean (typeName="mybean" )
* public class MyBean {...}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_beanDictionary}
*
*/
String typeName() default "";
/**
* The property name to use for representing the type name.
*
*
* This can be used to override the name used for the "_type" property used by the {@link #typeName()} setting.
*
*
* The default value if not specified is "_type" .
*
*
Example:
*
* // Use 'type' instead of '_type' for bean names.
* @Bean (typePropertyName="type" )
* public class MyBean {...}
*
*
* See Also:
*
* - {@link BeanContext#BEAN_beanTypePropertyName}
*
*/
String typePropertyName() default "";
}