001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.bean;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * Excludes a class, field, method, or constructor from bean introspection.
026 *
027 * <p>
028 * The bean-modeling sibling of {@code @MarshalledIgnore}: where {@code @MarshalledIgnore} (in
029 * <c>juneau-marshall</c>) controls whether the marshaller skips a type entirely at the wire-format
030 * layer, this annotation describes whether something participates in <i>bean detection</i>. It lives
031 * in <c>juneau-commons</c> so the bean-modeling layer can describe non-bean types and excluded bean
032 * members without depending on the marshalling layer.
033 *
034 * <p>
035 * Behavior depends on the target:
036 * <ul>
037 *    <li><b>TYPE (class)</b> — marks the class as <i>not a bean</i>. The marshaller falls through to
038 *       its other type-detection logic (object swaps, {@link BeanType @BeanType}-style
039 *       hints, {@code @Marshalled(as=STRING)}, etc.) instead of treating the class as a bean.
040 *    <li><b>FIELD</b> — excludes the field from bean property discovery. Use {@link #ignoreAccessors()}
041 *       to also suppress matching JavaBean accessors.
042 *    <li><b>METHOD</b> — excludes the getter/setter from bean property discovery.
043 *    <li><b>CONSTRUCTOR</b> — excludes the constructor from constructor detection.
044 * </ul>
045 *
046 * <h5 class='section'>Java Records:</h5>
047 * <p>
048 * Ignoring individual record components is not supported during parsing. Because records are
049 * immutable, all components must be provided to the canonical constructor. Applying this
050 * annotation to a record component's accessor method or field will exclude it from serialization
051 * output, but the parser will be unable to instantiate the record if the component value is missing
052 * from the input.
053 *
054 * <h5 class='section'>See Also:</h5><ul>
055 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/BeanIgnoreAnnotation">@BeanIgnore Annotation</a>
056 * </ul>
057 */
058@Documented
059@Target({ FIELD, METHOD, TYPE, CONSTRUCTOR })
060@Retention(RUNTIME)
061@Inherited
062public @interface BeanIgnore {
063
064   /**
065    * Optional description for the exposed API.
066    *
067    * @return The annotation value.
068    * @since 9.2.0
069    */
070   String[] description() default {};
071
072   /**
073    * When <jk>true</jk> and this annotation is on a <jk>field</jk>, JavaBean accessors (<c>getX</c>/<c>setX</c>,
074    * <c>isX</c>) for the same logical property are also excluded from bean metadata.
075    *
076    * <p>
077    * Default is <jk>false</jk>: {@code @BeanIgnore} on a field only excludes the field from field-based discovery;
078    * accessors can still expose the property (for example when bean field visibility is set to {@code NONE}).
079    * Set to <jk>true</jk> to omit the property from serialization and parsing while keeping accessors for other
080    * frameworks.
081    *
082    * @return The annotation value.
083    */
084   boolean ignoreAccessors() default false;
085
086}