001package ezvcard.property;
002
003import java.util.List;
004
005import ezvcard.VCard;
006import ezvcard.VCardVersion;
007import ezvcard.ValidationWarning;
008import ezvcard.parameter.EmailType;
009import ezvcard.parameter.Pid;
010
011/*
012 Copyright (c) 2012-2023, Michael Angstadt
013 All rights reserved.
014
015 Redistribution and use in source and binary forms, with or without
016 modification, are permitted provided that the following conditions are met: 
017
018 1. Redistributions of source code must retain the above copyright notice, this
019 list of conditions and the following disclaimer. 
020 2. Redistributions in binary form must reproduce the above copyright notice,
021 this list of conditions and the following disclaimer in the documentation
022 and/or other materials provided with the distribution. 
023
024 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
025 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
026 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
027 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
028 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
029 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
030 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
031 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
032 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
033 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
034
035 The views and conclusions contained in the software and documentation are those
036 of the authors and should not be interpreted as representing official policies, 
037 either expressed or implied, of the FreeBSD Project.
038 */
039
040/**
041 * <p>
042 * Defines an email address associated with the person.
043 * </p>
044 * 
045 * <p>
046 * <b>Code sample</b>
047 * </p>
048 * 
049 * <pre class="brush:java">
050 * VCard vcard = new VCard();
051 * 
052 * Email email = new Email("johndoe@hotmail.com");
053 * email.getTypes().add(EmailType.HOME);
054 * vcard.addEmail(email);
055 * 
056 * email = new Email("jdoe@company.com");
057 * email.getTypes().add(EmailType.WORK);
058 * email.setPref(1); //the most preferred email
059 * vcard.addEmail(email);
060 * </pre>
061 * 
062 * <p>
063 * <b>Property name:</b> {@code EMAIL}
064 * </p>
065 * <p>
066 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
067 * </p>
068 * @author Michael Angstadt
069 * @see <a href="http://tools.ietf.org/html/rfc6350#page-36">RFC 6350 p.36</a>
070 * @see <a href="http://tools.ietf.org/html/rfc2426#page-15">RFC 2426 p.15</a>
071 * @see <a href="http://www.imc.org/pdi/vcard-21.doc">vCard 2.1 p.15</a>
072 */
073public class Email extends TextProperty implements HasAltId {
074        /**
075         * Creates an email property.
076         * @param email the email (e.g. "johndoe@example.com")
077         */
078        public Email(String email) {
079                super(email);
080        }
081
082        /**
083         * Copy constructor.
084         * @param original the property to make a copy of
085         */
086        public Email(Email original) {
087                super(original);
088        }
089
090        /**
091         * Gets the list that stores this property's email types (TYPE parameters).
092         * @return the email types (this list is mutable) (e.g. "INTERNET", "WORK")
093         */
094        public List<EmailType> getTypes() {
095                return parameters.new TypeParameterList<EmailType>() {
096                        @Override
097                        protected EmailType _asObject(String value) {
098                                return EmailType.get(value);
099                        }
100                };
101        }
102
103        @Override
104        public List<Pid> getPids() {
105                return super.getPids();
106        }
107
108        @Override
109        public Integer getPref() {
110                return super.getPref();
111        }
112
113        @Override
114        public void setPref(Integer pref) {
115                super.setPref(pref);
116        }
117
118        //@Override
119        public String getAltId() {
120                return parameters.getAltId();
121        }
122
123        //@Override
124        public void setAltId(String altId) {
125                parameters.setAltId(altId);
126        }
127
128        @Override
129        protected void _validate(List<ValidationWarning> warnings, VCardVersion version, VCard vcard) {
130                super._validate(warnings, version, vcard);
131
132                for (EmailType type : getTypes()) {
133                        if (type == EmailType.PREF) {
134                                //ignore because it is converted to a PREF parameter for 4.0 vCards
135                                continue;
136                        }
137                        if (!type.isSupportedBy(version)) {
138                                warnings.add(new ValidationWarning(9, type.getValue()));
139                        }
140                }
141        }
142
143        @Override
144        public Email copy() {
145                return new Email(this);
146        }
147}