1package eu.siacs.conversations.xmpp;
2
3import org.jxmpp.jid.impl.JidCreate;
4import org.jxmpp.jid.parts.Domainpart;
5import org.jxmpp.jid.parts.Localpart;
6import org.jxmpp.jid.parts.Resourcepart;
7import org.jxmpp.stringprep.XmppStringprepException;
8
9import java.io.Serializable;
10
11public interface Jid extends Comparable<Jid>, Serializable, CharSequence {
12
13 static Jid of(CharSequence local, CharSequence domain, CharSequence resource) {
14 if (resource == null) {
15 return ofLocalAndDomain(local, domain);
16 }
17 try {
18 return new WrappedJid(JidCreate.entityFullFrom(
19 Localpart.fromUnescaped(local.toString()),
20 Domainpart.from(domain.toString()),
21 Resourcepart.from(resource.toString())
22 ));
23 } catch (XmppStringprepException e) {
24 throw new IllegalArgumentException(e);
25 }
26 }
27
28 static Jid ofEscaped(CharSequence local, CharSequence domain, CharSequence resource) {
29 try {
30 if (resource == null) {
31 return new WrappedJid(
32 JidCreate.bareFrom(
33 Localpart.from(local.toString()),
34 Domainpart.from(domain.toString())
35 )
36 );
37 }
38 return new WrappedJid(JidCreate.entityFullFrom(
39 Localpart.from(local.toString()),
40 Domainpart.from(domain.toString()),
41 Resourcepart.from(resource.toString())
42 ));
43 } catch (XmppStringprepException e) {
44 throw new IllegalArgumentException(e);
45 }
46 }
47
48 /**
49 * Creates a bare JID with only the domain part, e.g. <code>capulet.com</code>
50 *
51 * @param domain The domain.
52 * @return The JID.
53 * @throws NullPointerException If the domain is null.
54 * @throws IllegalArgumentException If the domain or local part are not valid.
55 */
56 static Jid ofDomain(CharSequence domain) {
57 try {
58 return new WrappedJid(JidCreate.domainBareFrom(domain));
59 } catch (XmppStringprepException e) {
60 throw new IllegalArgumentException(e);
61 }
62 }
63
64 /**
65 * Creates a bare JID with a local and domain part, e.g. <code>juliet@capulet.com</code>
66 *
67 * @param local The local part.
68 * @param domain The domain.
69 * @return The JID.
70 * @throws NullPointerException If the domain is null.
71 * @throws IllegalArgumentException If the domain or local part are not valid.
72 */
73 static Jid ofLocalAndDomain(CharSequence local, CharSequence domain) {
74 try {
75 return new WrappedJid(
76 JidCreate.bareFrom(
77 Localpart.fromUnescaped(local.toString()),
78 Domainpart.from(domain.toString())
79 )
80 );
81 } catch (XmppStringprepException e) {
82 throw new IllegalArgumentException(e);
83 }
84 }
85
86 /**
87 * Creates a JID from an unescaped string. The format must be
88 * <blockquote><p>[ localpart "@" ] domainpart [ "/" resourcepart ]</p></blockquote>
89 * The input string will be escaped.
90 *
91 * @param jid The JID.
92 * @return The JID.
93 * @throws NullPointerException If the jid is null.
94 * @throws IllegalArgumentException If the jid could not be parsed or is not valid.
95 * @see <a href="https://xmpp.org/extensions/xep-0106.html">XEP-0106: JID Escaping</a>
96 */
97 static Jid of(CharSequence jid) {
98 if (jid instanceof Jid) {
99 return (Jid) jid;
100 }
101 try {
102 return new WrappedJid(JidCreate.fromUnescaped(jid));
103 } catch (XmppStringprepException e) {
104 throw new IllegalArgumentException(e);
105 }
106 }
107
108 /**
109 * Creates a JID from a escaped JID string. The format must be
110 * <blockquote><p>[ localpart "@" ] domainpart [ "/" resourcepart ]</p></blockquote>
111 * This method should be used, when parsing JIDs from the XMPP stream.
112 *
113 * @param jid The JID.
114 * @return The JID.
115 * @throws NullPointerException If the jid is null.
116 * @throws IllegalArgumentException If the jid could not be parsed or is not valid.
117 * @see <a href="https://xmpp.org/extensions/xep-0106.html">XEP-0106: JID Escaping</a>
118 */
119 static Jid ofEscaped(CharSequence jid) {
120 try {
121 return new WrappedJid(JidCreate.from(jid));
122 } catch (XmppStringprepException e) {
123 e.printStackTrace();
124 throw new IllegalArgumentException(e);
125 }
126 }
127
128 /**
129 * Checks if the JID is a full JID.
130 * <blockquote>
131 * <p>The term "full JID" refers to an XMPP address of the form <localpart@domainpart/resourcepart> (for a particular authorized client or device associated with an account) or of the form <domainpart/resourcepart> (for a particular resource or script associated with a server).</p>
132 * </blockquote>
133 *
134 * @return True, if the JID is a full JID; otherwise false.
135 */
136 boolean isFullJid();
137
138 /**
139 * Checks if the JID is a bare JID.
140 * <blockquote>
141 * <p>The term "bare JID" refers to an XMPP address of the form <localpart@domainpart> (for an account at a server) or of the form <domainpart> (for a server).</p>
142 * </blockquote>
143 *
144 * @return True, if the JID is a bare JID; otherwise false.
145 */
146 boolean isBareJid();
147
148 /**
149 * Checks if the JID is a domain JID, i.e. if it has no local part.
150 *
151 * @return True, if the JID is a domain JID, i.e. if it has no local part.
152 */
153 boolean isDomainJid();
154
155 /**
156 * Gets the bare JID representation of this JID, i.e. removes the resource part.
157 * <blockquote>
158 * <p>The term "bare JID" refers to an XMPP address of the form <localpart@domainpart> (for an account at a server) or of the form <domainpart> (for a server).</p>
159 * </blockquote>
160 *
161 * @return The bare JID.
162 * @see #withResource(CharSequence)
163 */
164 Jid asBareJid();
165
166 /**
167 * Creates a new full JID with a resource and the same local and domain part of the current JID.
168 *
169 * @param resource The resource.
170 * @return The full JID with a resource.
171 * @throws IllegalArgumentException If the resource is not a valid resource part.
172 * @see #asBareJid()
173 */
174 Jid withResource(CharSequence resource);
175
176
177 /**
178 * Gets the local part of the JID, also known as the name or node.
179 * <blockquote>
180 * <p><cite><a href="https://tools.ietf.org/html/rfc7622#section-3.3">3.3. Localpart</a></cite></p>
181 * <p>The localpart of a JID is an optional identifier placed before the
182 * domainpart and separated from the latter by the '@' character.
183 * Typically, a localpart uniquely identifies the entity requesting and
184 * using network access provided by a server (i.e., a local account),
185 * although it can also represent other kinds of entities (e.g., a
186 * chatroom associated with a multi-user chat service [XEP-0045]). The
187 * entity represented by an XMPP localpart is addressed within the
188 * context of a specific domain (i.e., <localpart@domainpart>).</p>
189 * </blockquote>
190 *
191 * @return The local part or null.
192 * @see #getEscapedLocal()
193 */
194 String getLocal();
195
196 /**
197 * Gets the escaped local part of the JID.
198 *
199 * @return The escaped local part or null.
200 * @see #getLocal()
201 * @since 0.8.0
202 */
203 String getEscapedLocal();
204
205 /**
206 * Gets the domain part.
207 * <blockquote>
208 * <p><cite><a href="https://tools.ietf.org/html/rfc7622#section-3.2">3.2. Domainpart</a></cite></p>
209 * <p>The domainpart is the primary identifier and is the only REQUIRED
210 * element of a JID (a mere domainpart is a valid JID). Typically,
211 * a domainpart identifies the "home" server to which clients connect
212 * for XML routing and data management functionality.</p>
213 * </blockquote>
214 *
215 * @return The domain part.
216 */
217 String getDomain();
218
219 /**
220 * Gets the resource part.
221 * <blockquote>
222 * <p><cite><a href="https://tools.ietf.org/html/rfc7622#section-3.4">3.4. Resourcepart</a></cite></p>
223 * <p>The resourcepart of a JID is an optional identifier placed after the
224 * domainpart and separated from the latter by the '/' character. A
225 * resourcepart can modify either a <localpart@domainpart> address or a
226 * mere <domainpart> address. Typically, a resourcepart uniquely
227 * identifies a specific connection (e.g., a device or location) or
228 * object (e.g., an occupant in a multi-user chatroom [XEP-0045])
229 * belonging to the entity associated with an XMPP localpart at a domain
230 * (i.e., <localpart@domainpart/resourcepart>).</p>
231 * </blockquote>
232 *
233 * @return The resource part or null.
234 */
235 String getResource();
236
237 /**
238 * Returns the JID in escaped form as described in <a href="https://xmpp.org/extensions/xep-0106.html">XEP-0106: JID Escaping</a>.
239 *
240 * @return The escaped JID.
241 * @see #toString()
242 */
243 String toEscapedString();
244}