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