Source code

001package ezvcard.property;
002
003import java.io.File;
004import java.io.IOException;
005import java.io.InputStream;
006import java.util.List;
007import java.util.Map;
008
009import ezvcard.VCard;
010import ezvcard.VCardVersion;
011import ezvcard.ValidationWarning;
012import ezvcard.parameter.KeyType;
013
014/*
015 Copyright (c) 2012-2018, Michael Angstadt
016 All rights reserved.
017
018 Redistribution and use in source and binary forms, with or without
019 modification, are permitted provided that the following conditions are met: 
020
021 1. Redistributions of source code must retain the above copyright notice, this
022 list of conditions and the following disclaimer. 
023 2. Redistributions in binary form must reproduce the above copyright notice,
024 this list of conditions and the following disclaimer in the documentation
025 and/or other materials provided with the distribution. 
026
027 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
028 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
029 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
030 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
031 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
032 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
033 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
034 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
035 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
036 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
037
038 The views and conclusions contained in the software and documentation are those
039 of the authors and should not be interpreted as representing official policies, 
040 either expressed or implied, of the FreeBSD Project.
041 */
042
043/**
044 * <p>
045 * Defines a public encryption key.
046 * </p>
047 * 
048 * <p>
049 * <b>Code sample (creating)</b>
050 * </p>
051 * 
052 * <pre class="brush:java">
053 * VCard vcard = new VCard();
054 * 
055 * //URL
056 * Key key = new Key("http://www.mywebsite.com/my-public-key.pgp", KeyType.PGP);
057 * vcard.addKey(key);
058 * 
059 * //binary data
060 * byte data[] = ...
061 * key = new Key(data, KeyType.PGP);
062 * vcard.addKey(key);
063 * 
064 * //plain text value
065 * key = new Key();
066 * key.setText("...", KeyType.PGP);
067 * vcard.addKey(key);
068 * </pre>
069 * 
070 * <p>
071 * <b>Code sample (retrieving)</b>
072 * </p>
073 * 
074 * <pre class="brush:java">
075 * VCard vcard = ...
076 * for (Key key : vcard.getKeys()) {
077 *   KeyType contentType = key.getContentType(); //e.g. "application/pgp-keys"
078 * 
079 *   String url = key.getUrl();
080 *   if (url != null) {
081 *     //property value is a URL
082 *     continue;
083 *   }
084 *   
085 *   byte[] data = key.getData();
086 *   if (data != null) {
087 *     //property value is binary data
088 *     continue;
089 *   }
090 *   
091 *   String text = key.getText();
092 *   if (text != null) {
093 *     //property value is plain-text
094 *     continue;
095 *   }
096 * }
097 * </pre>
098 * 
099 * <p>
100 * <b>Property name:</b> {@code KEY}
101 * </p>
102 * <p>
103 * <b>Supported versions:</b> {@code 2.1, 3.0, 4.0}
104 * </p>
105 * @author Michael Angstadt
106 * @see <a href="http://tools.ietf.org/html/rfc6350#page-48">RFC 6350 p.48</a>
107 * @see <a href="http://tools.ietf.org/html/rfc2426#page-26">RFC 2426 p.26</a>
108 * @see <a href="http://www.imc.org/pdi/vcard-21.doc">vCard 2.1 p.22</a>
109 */
110public class Key extends BinaryProperty<KeyType> {
111        private String text;
112
113        /**
114         * Creates an empty key property.
115         */
116        public Key() {
117                super();
118        }
119
120        /**
121         * Creates a key property.
122         * @param data the binary data
123         * @param type the type of key (e.g. PGP)
124         */
125        public Key(byte data[], KeyType type) {
126                super(data, type);
127        }
128
129        /**
130         * Creates a key property.
131         * @param url the URL to the key (vCard 4.0 only)
132         * @param type the type of key (e.g. PGP)
133         */
134        public Key(String url, KeyType type) {
135                super(url, type);
136        }
137
138        /**
139         * Creates a key property.
140         * @param in an input stream to the binary data (will be closed)
141         * @param type the content type (e.g. PGP)
142         * @throws IOException if there's a problem reading from the input stream
143         */
144        public Key(InputStream in, KeyType type) throws IOException {
145                super(in, type);
146        }
147
148        /**
149         * Creates a key property.
150         * @param file the key file
151         * @param type the content type (e.g. PGP)
152         * @throws IOException if there's a problem reading from the file
153         */
154        public Key(File file, KeyType type) throws IOException {
155                super(file, type);
156        }
157
158        /**
159         * Copy constructor.
160         * @param original the property to make a copy of
161         */
162        public Key(Key original) {
163                super(original);
164                text = original.text;
165        }
166
167        /**
168         * Sets a plain text representation of the key.
169         * @param text the key in plain text
170         * @param type the key type
171         */
172        public void setText(String text, KeyType type) {
173                this.text = text;
174                data = null;
175                url = null;
176                setContentType(type);
177        }
178
179        /**
180         * Gets the plain text representation of the key.
181         * @return the key in plain text
182         */
183        public String getText() {
184                return text;
185        }
186
187        @Override
188        public void setUrl(String url, KeyType type) {
189                super.setUrl(url, type);
190                text = null;
191        }
192
193        @Override
194        public void setData(byte[] data, KeyType type) {
195                super.setData(data, type);
196                text = null;
197        }
198
199        @Override
200        protected void _validate(List<ValidationWarning> warnings, VCardVersion version, VCard vcard) {
201                if (url == null && data == null && text == null) {
202                        warnings.add(new ValidationWarning(8));
203                }
204
205                if (url != null && (version == VCardVersion.V2_1 || version == VCardVersion.V3_0)) {
206                        warnings.add(new ValidationWarning(15));
207                }
208        }
209
210        @Override
211        protected Map<String, Object> toStringValues() {
212                Map<String, Object> values = super.toStringValues();
213                values.put("text", text);
214                return values;
215        }
216
217        @Override
218        public Key copy() {
219                return new Key(this);
220        }
221
222        @Override
223        public int hashCode() {
224                final int prime = 31;
225                int result = super.hashCode();
226                result = prime * result + ((text == null) ? 0 : text.hashCode());
227                return result;
228        }
229
230        @Override
231        public boolean equals(Object obj) {
232                if (this == obj) return true;
233                if (!super.equals(obj)) return false;
234                Key other = (Key) obj;
235                if (text == null) {
236                        if (other.text != null) return false;
237                } else if (!text.equals(other.text)) return false;
238                return true;
239        }
240}