001 package ezvcard.property;
002
003 import java.util.EnumSet;
004 import java.util.List;
005 import java.util.Set;
006 import java.util.UUID;
007
008 import ezvcard.VCard;
009 import ezvcard.VCardVersion;
010 import ezvcard.Warning;
011 import ezvcard.parameter.VCardParameters;
012
013 /*
014 Copyright (c) 2013, 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 * Maps a globally-unique URI to a PID parameter value. The PID parameter can be
045 * set on any property where multiple instances are allowed (such as
046 * {@link Email} or {@link Address}, but not {@link StructuredName} because only
047 * 1 instance of it is allowed). It allows an individual property instance to be
048 * uniquely identifiable.
049 * </p>
050 *
051 * <p>
052 * The CLIENTPIDMAP property and the PID parameter are used during the
053 * synchronization (merging) process of two versions of the same vCard. For
054 * example, if the user has a copy of her vCard on her desktop computer and her
055 * smart phone, and she makes different modifications to each copy, then the two
056 * copies could be synchronized in order to merge all the changes into a single,
057 * new vCard.
058 * </p>
059 *
060 * <p>
061 * <b>Code sample</b>
062 * </p>
063 *
064 * <pre class="brush:java">
065 * VCard vcard = new VCard();
066 *
067 * Address adr = new Address();
068 * adr.addPid(1, 1);
069 * vcard.addAddress(adr);
070 *
071 * Email email = new Email("my-email@hotmail.com");
072 * emai.addPid(1, 1);
073 * vcard.addEmail(email);
074 * email = new Email("my-other-email@yahoo.com");
075 * emai.addPid(2, 2);
076 * vcard.addEmail(email);
077 *
078 * //specify the URI to use
079 * ClientPidMap clientpidmap = new ClientPidMap(1, "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af");
080 * vcard.addClientPidMap(clientpidmap);
081 *
082 * //generate a random URI
083 * clientpidmap = ClientPidMap.random(2);
084 * vcard.addClientPidMap(clientpidmap);
085 * </pre>
086 *
087 * <p>
088 * <b>Property name:</b> {@code CLIENTPIDMAP}
089 * </p>
090 * <p>
091 * <b>Supported versions:</b> {@code 4.0}
092 * </p>
093 * @author Michael Angstadt
094 */
095 public class ClientPidMap extends VCardProperty {
096 private Integer pid;
097 private String uri;
098
099 /**
100 * Creates a client PID map property.
101 * @param pid the PID
102 * @param uri the globally unique URI
103 */
104 public ClientPidMap(Integer pid, String uri) {
105 this.pid = pid;
106 this.uri = uri;
107 }
108
109 /**
110 * Generates a CLIENTPIDMAP type that contains a random UID URI.
111 * @param pid the PID
112 * @return a CLIENTPIDMAP type with a random UID URI
113 */
114 public static ClientPidMap random(Integer pid) {
115 String uuid = UUID.randomUUID().toString();
116 return new ClientPidMap(pid, "urn:uuid:" + uuid);
117 }
118
119 @Override
120 public Set<VCardVersion> _supportedVersions() {
121 return EnumSet.of(VCardVersion.V4_0);
122 }
123
124 /**
125 * Gets the value that is used to link the URI in this property to the
126 * property that the URI belongs to.
127 * @return the PID
128 * @see VCardParameters#getPids
129 */
130 public Integer getPid() {
131 return pid;
132 }
133
134 /**
135 * Gets the value that is used to link the URI in this property to the
136 * property that the URI belongs to.
137 * @param pid the PID
138 * @see VCardParameters#getPids
139 */
140 public void setPid(Integer pid) {
141 this.pid = pid;
142 }
143
144 /**
145 * Gets the URI.
146 * @return the URI
147 */
148 public String getUri() {
149 return uri;
150 }
151
152 /**
153 * Sets the URI.
154 * @param uri the URI
155 */
156 public void setUri(String uri) {
157 this.uri = uri;
158 }
159
160 @Override
161 protected void _validate(List<Warning> warnings, VCardVersion version, VCard vcard) {
162 if (pid == null && uri == null) {
163 warnings.add(new Warning(8));
164 }
165 }
166 }