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.marshall;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.commons.bean.*;
025
026/**
027 * Skip a type entirely during marshalling.
028 *
029 * <p>
030 * Serializers output {@code null} for instances of the annotated type and parsers return {@code null}
031 * when asked to instantiate it. This is a marshalling-layer concern: the wire format renders the
032 * value as {@code null} regardless of what (if anything) the bean-modeling layer would do with the
033 * type.
034 *
035 * <p>
036 * Bean-modeling decisions are controlled by the sibling annotation
037 * {@link BeanIgnore @BeanIgnore} (in <c>juneau-commons</c>), which is responsible for excluding
038 * classes from bean detection ("this isn't a bean — fall through to swap/{@code @Marshalled(as=STRING)}/etc.")
039 * and for excluding fields, methods, and constructors from bean property/constructor detection.
040 *
041 * <p>
042 * The two annotations are independent and may be combined:
043 * <ul>
044 *    <li>{@code @MarshalledIgnore} alone — the class still participates in bean detection (it may be
045 *       treated as a bean by the modeling layer) but the marshaller emits {@code null}.
046 *    <li>{@code @BeanIgnore} alone — the class is not a bean for modeling purposes, but the marshaller
047 *       still tries to render it (typically via {@code toString()} or an installed swap).
048 *    <li>Both — the class is not a bean and the marshaller emits {@code null}.
049 * </ul>
050 *
051 * <h5 class='section'>See Also:</h5><ul>
052 *    <li class='ja'>{@link BeanIgnore}
053 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/BeanIgnoreAnnotation#format-side-marshalledignore">Format Side: @MarshalledIgnore</a>
054 * </ul>
055 */
056@Documented
057@Target({ TYPE })
058@Retention(RUNTIME)
059@Inherited
060public @interface MarshalledIgnore {
061
062   /**
063    * Optional description for the exposed API.
064    *
065    * @return The annotation value.
066    * @since 9.2.0
067    */
068   String[] description() default {};
069
070}