001package ezvcard.io.json;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import java.lang.annotation.Target;
007
008import com.fasterxml.jackson.databind.annotation.JsonSerialize;
009
010import ezvcard.VCard;
011import ezvcard.property.ProductId;
012
013/*
014 Copyright (c) 2012-2023, Michael Angstadt
015 All rights reserved.
016
017 Redistribution and use in source and binary forms, with or without
018 modification, are permitted provided that the following conditions are met: 
019
020 1. Redistributions of source code must retain the above copyright notice, this
021 list of conditions and the following disclaimer. 
022 2. Redistributions in binary form must reproduce the above copyright notice,
023 this list of conditions and the following disclaimer in the documentation
024 and/or other materials provided with the distribution. 
025
026 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
027 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
028 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
029 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
030 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
031 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
032 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
033 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
034 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
035 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
036
037 The views and conclusions contained in the software and documentation are those
038 of the authors and should not be interpreted as representing official policies, 
039 either expressed or implied, of the FreeBSD Project.
040 */
041
042/**
043 * <p>
044 * Defines settings for how a {@link VCard} should be serialized when written to
045 * JSON. This annotation should be used in combination with
046 * {@link JsonSerialize &#64;JsonSerialize} on getter methods that return
047 * {@link VCard} objects.
048 * </p>
049 * <p>
050 * <b>Example:</b>
051 * </p>
052 * 
053 * <pre class="brush:java">
054 * class Person {
055 *   private VCard contact;
056 * 
057 *   &#064;JsonSerialize(using = JCardSerializer.class)
058 *   &#064;JCardOptions(addProdId = false, versionStrict = false)
059 *   public VCard getContact() {
060 *     return contact;
061 *   }
062 * 
063 *   //...
064 * }
065 * </pre>
066 * @author Buddy Gorven
067 */
068@Target({ ElementType.ANNOTATION_TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE })
069@Retention(RetentionPolicy.RUNTIME)
070public @interface JCardFormat {
071        /**
072         * Sets whether to add a {@link ProductId} property to the vCard that marks
073         * it as having been generated by this library (defaults to true).
074         * @return true to add a {@link ProductId} property, false not to
075         */
076        boolean addProdId() default true;
077
078        /**
079         * Sets whether to exclude properties that do not support vCard version 4.0
080         * from the written vCard (defaults to true).
081         * @return true to perform the exclusions, false to include everything
082         */
083        boolean versionStrict() default true;
084}