001/**
002 *
003 * Copyright © 2014-2020 Florian Schmaus
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.jxmpp.jid;
018
019import java.io.Serializable;
020
021import org.jxmpp.jid.parts.Domainpart;
022import org.jxmpp.jid.parts.Localpart;
023import org.jxmpp.jid.parts.Resourcepart;
024
025/**
026 * An <b>XMPP address</b>, also known as JID (formerly for "Jabber Identifier"), which acts as globally unique address
027 * within the XMPP network.
028 * <p>
029 * JIDs are created from {@link String} or {@link CharSequence} with the {@link org.jxmpp.jid.impl.JidCreate} utility.
030 * </p>
031 * 
032 * <pre>
033 * Jid jid = JidCreate.from("juliet@capulet.org/balcony");
034 * EntityBareJid bareJid = JidCreate.entityBareFrom("romeo@montague.net");
035 * </pre>
036 * <p>
037 * This is the super interface for all JID types, which are constructed from two dimensions: Bare/Full and
038 * Domain/Entity. Every JID consists at least of a {@link Domainpart}. Bare JID types do not come with a
039 * {@link Resourcepart}, full JID types always have a {@link Resourcepart}. Domain JID types do not possess a
040 * {@link Localpart}, whereas entity JID types always do.
041 * </p>
042 * <p>
043 * The following table shows a few examples of JID types.
044 * </p>
045 * <table>
046 * <caption>XMPP Address Types</caption>
047 * <tr>
048 * <td>Example</td>
049 * <td>Type</td>
050 * </tr>
051 * <tr>
052 * <td><code>example.org</code></td>
053 * <td>{@link DomainBareJid}</td>
054 * </tr>
055 * <tr>
056 * <td><code>example.org/resource</code></td>
057 * <td>{@link DomainFullJid}</td>
058 * </tr>
059 * <tr>
060 * <td><code>user@example.org</code></td>
061 * <td>{@link EntityBareJid}</td>
062 * </tr>
063 * <tr>
064 * <td><code>user@example.org/resource</code></td>
065 * <td>{@link EntityFullJid}</td>
066 * </tr>
067 * </table>
068 * <p>
069 * You can retrieve the escaped String representing the Jid with {@link #toString()} or the unescaped String of the JID
070 * with {@link #asUnescapedString()}.
071 * </p>
072 * <h2>URL Encoded JIDs</h2>
073 * <p>
074 * The URL encoded representation of a JID is ideal if a JID should be stored as part of a path name, e.g. as file name.
075 * You can retrieve this information using {@link #asUrlEncodedString()}. The JidCreate API provides methods to create
076 * JIDs from URL encoded Strings like {@link org.jxmpp.jid.impl.JidCreate#fromUrlEncoded(CharSequence)}.
077 * </p>
078 *
079 *
080 * @see <a href="http://xmpp.org/rfcs/rfc6120.html#arch-addresses">RFC 6120 (XMPP: Core) § 2.1 Global Addresses</a>
081 * @see <a href="http://xmpp.org/rfcs/rfc6122.html#addressing-fundamentals">RFC 6122 (XMPP: Address Format) § 2.1
082 * Fundamentals</a>
083 */
084public interface Jid extends Comparable<Jid>, CharSequence, Serializable {
085
086        /**
087         * Get the {@link Domainpart} of this Jid.
088         *
089         * @return the domainpart.
090         */
091        Domainpart getDomain();
092
093        /**
094         * Returns the String representation of this JID.
095         *
096         * @return the String representation of this JID.
097         */
098        @Override
099        String toString();
100
101        /**
102         * Return the <b>unescaped</b> String representation of this JID.
103         * <p>
104         * Since certain Unicode code points are disallowed in the localpart of a JID by the required stringprep profile,
105         * those need to get escaped when used in a real JID. The unescaped representation of the JID is only for
106         * presentation to a human user or for gatewaying to a non-XMPP system.
107         * </p>
108         * For example, if the users inputs {@code 'at&t guy@example.com'}, the escaped real JID created with
109         * {@link org.jxmpp.jid.impl.JidCreate} will be {@code 'at\26t\20guy@example.com'}, which is what
110         * {@link Jid#toString()} will return. But {@link Jid#asUnescapedString()} will return again
111         * {@code 'at&t guy@example.com'}.
112         *
113         * @return the unescaped String representation of this JID.
114         */
115        String asUnescapedString();
116
117        /**
118         * Get the URL encoded version of this JID.
119         *
120         * @return the URL encoded version of this JID.
121         * @since 0.7.0
122         */
123        String asUrlEncodedString();
124
125        /**
126         * Check if this is a {@link EntityBareJid} or {@link EntityFullJid}.
127         *
128         * @return true if this is an instance of BareJid or FullJid.
129         */
130        boolean isEntityJid();
131
132        /**
133         * Check if this is an instance of {@link EntityBareJid}.
134         * 
135         * @return true if this is an instance of EntityBareJid
136         */
137        boolean isEntityBareJid();
138
139        /**
140         * Check if this is an instance of {@link EntityFullJid}.
141         * 
142         * @return true if this is an instance of EntityFullJid
143         */
144        boolean isEntityFullJid();
145
146        /**
147         * Check if this is an instance of {@link DomainBareJid}.
148         *  
149         * @return true if this is an instance of DomainBareJid
150         */
151        boolean isDomainBareJid();
152
153        /**
154         * Check if this is an instance of {@link DomainFullJid}.
155         * 
156         * @return true if this is an instance of DomainFullJid
157         */
158        boolean isDomainFullJid();
159
160        /**
161         * Check if this is an instance of {@link EntityBareJid} or {@link DomainBareJid}.
162         * 
163         * @return true if this is an instance of BareJid or DomainBareJid
164         */
165        boolean hasNoResource();
166
167        /**
168         * Check if this is a Jid with a {@link Resourcepart}.
169         *
170         * @return true if this Jid has a resourcepart.
171         */
172        boolean hasResource();
173
174        /**
175         * Check if this is a Jid with a {@link Localpart}.
176         *
177         * @return true if this Jid has a localpart.
178         */
179        boolean hasLocalpart();
180
181        /**
182         * Return a JID created by removing the Resourcepart from this JID.
183         *
184         * @return this Jid without a Resourcepart.
185         */
186        BareJid asBareJid();
187
188        /**
189         * Convert this Jid to a {@link EntityBareJid} if possible.
190         *
191         * @return the corresponding {@link EntityBareJid} or null.
192         */
193        EntityBareJid asEntityBareJidIfPossible();
194
195        /**
196         * Convert this Jid to a {@link EntityBareJid} or throw an {@code IllegalStateException} if this is not possible.
197         * 
198         * @return the corresponding {@link EntityBareJid}.
199         */
200        EntityBareJid asEntityBareJidOrThrow();
201
202        /**
203         * Convert this Jid to a {@link EntityFullJid} if possible.
204         *
205         * @return the corresponding {@link EntityFullJid} or null.
206         */
207        EntityFullJid asEntityFullJidIfPossible();
208
209        /**
210         * Convert this Jid to a {@link EntityFullJid} or throw an {@code IllegalStateException} if this is not possible.
211         * 
212         * @return the corresponding {@link EntityFullJid}.
213         */
214        EntityFullJid asEntityFullJidOrThrow();
215
216        /**
217         * Convert this Jid to a {@link EntityJid} if possible.
218         *
219         * @return the corresponding {@link EntityJid} or null.
220         */
221        EntityJid asEntityJidIfPossible();
222
223        /**
224         * Convert this Jid to a {@link EntityJid} or throw an {@code IllegalStateException} if this is not possible.
225         * 
226         * @return the corresponding {@link EntityJid}.
227         */
228        EntityJid asEntityJidOrThrow();
229
230        /**
231         * Convert this Jid to a {@link FullJid} if possible.
232         *
233         * @return the corresponding {@link FullJid} or null.
234         */
235        FullJid asFullJidIfPossible();
236
237        /**
238         * Convert this Jid to a {@link FullJid} or throw an {@code IllegalStateException} if this is not possible.
239         * 
240         * @return the corresponding {@link FullJid}.
241         */
242        EntityFullJid asFullJidOrThrow();
243
244        /**
245         * Convert this Jid to a {@link DomainBareJid}.
246         * <p>
247         * Note that it is always possible to convert a Jid to a DomainBareJid, since every Jid has a domain part.
248         * </p>
249         *
250         * @return the corresponding DomainBareJid.
251         */
252        DomainBareJid asDomainBareJid();
253
254        /**
255         * Convert this Jid to a {@link DomainFullJid} if possible.
256         *
257         * @return the corresponding DomainFullJid or null.
258         */
259        DomainFullJid asDomainFullJidIfPossible();
260
261        /**
262         * Convert this Jid to a {@link DomainFullJid} or throw an {@code IllegalStateException} if this is not possible.
263         * 
264         * @return the corresponding {@link DomainFullJid}.
265         */
266        DomainFullJid asDomainFullJidOrThrow();
267
268        /**
269         * Get the resourcepart of this JID or null.
270         * <p>
271         * If the JID is of form {@code <localpart@domain.example/resource>} then this method returns 'resource'. If the JID no
272         * resourcepart, then <code>null</code> is returned.
273         * </p>
274         * 
275         * @return the resource of this JID or null.
276         */
277        Resourcepart getResourceOrNull();
278
279        /**
280         * Get the resourcepart of this JID or return the empty resourcepart.
281         * <p>
282         * If the JID is of form {@code <localpart@domain.example/resource>} then this method returns 'resource'. If the JID no
283         * resourcepart, then {@link org.jxmpp.jid.parts.Resourcepart#EMPTY} is returned.
284         * </p>
285         * 
286         * @return the resource of this JID or the empty resourcepart.
287         */
288        Resourcepart getResourceOrEmpty();
289
290        /**
291         * Get the resourcepart of this JID or throw an {@code IllegalStateException}.
292         * <p>
293         * If the JID is of form {@code <localpart@domain.example/resource>} then this method returns 'resource'. If the JID no
294         * resourcepart, then an {@code IllegalStateException} is thrown.
295         * </p>
296         * 
297         * @return the resource of this JID.
298         */
299        Resourcepart getResourceOrThrow();
300
301        /**
302         * Get the localpart of this JID or null.
303         * <p>
304         * If the JID is of form {@code <localpart@domain.example>} then this method returns 'localpart'. If the JID has no
305         * localpart, then <code>null</code> is returned.
306         * </p>
307         * 
308         * @return the localpart of this JID or null.
309         */
310        Localpart getLocalpartOrNull();
311
312        /**
313         * Get the localpart of this JID or throw an {@code IllegalStateException}.
314         * <p>
315         * If the JID is of form {@code <localpart@domain.example>} then this method returns 'localpart'. If the JID has no
316         * localpart, then <code>null</code> is returned.
317         * </p>
318         * 
319         * @return the localpart of this JID.
320         */
321        Localpart getLocalpartOrThrow();
322
323        /**
324         * Check if this JID is the parent of another JID. The <b>parent of</b> relation is defined, under the
325         * precondition that the JID parts (localpart, domainpart and resourcepart) are equal, as follows:
326         * <pre>
327         * | this JID (parentOf) | other JID           | result |
328         * |---------------------+---------------------+--------|
329         * | dom.example         | dom.example         | true   |
330         * | dom.example         | dom.example/res     | true   |
331         * | dom.example         | loc@dom.example     | true   |
332         * | dom.example         | loc@dom.example/res | true   |
333         * | dom.example/res     | dom.exmple          | false  |
334         * | dom.example/res     | dom.example/res     | true   |
335         * | dom.example/res     | loc@dom.example     | false  |
336         * | dom.example/res     | loc@dom.example/res | false  |
337         * | loc@dom.example     | dom.example         | false  |
338         * | loc@dom.example     | dom.example/res     | false  |
339         * | loc@dom.example     | loc@dom.example     | true   |
340         * | loc@dom.example     | loc@dom.example/res | true   |
341         * | loc@dom.example/res | dom.example         | false  |
342         * | loc@dom.example/res | dom.example/res     | false  |
343         * | loc@dom.example/res | loc@dom.example     | false  |
344         * | loc@dom.example/res | loc@dom.example/res | true   |
345         * </pre>
346         * 
347         * @param jid
348         *            the other JID to compare with
349         * @return true if this JID is a parent of the given JID.
350         */
351        boolean isParentOf(Jid jid);
352
353        /**
354         * See {@link #isParentOf(Jid)}.
355         *
356         * @param bareJid the bare JID.
357         * @return true if this JID is a parent of the given JID.
358         */
359        boolean isParentOf(EntityBareJid bareJid);
360
361        /**
362         * See {@link #isParentOf(Jid)}.
363         *
364         * @param fullJid the full JID.
365         * @return true if this JID is a parent of the given JID.
366         */
367        boolean isParentOf(EntityFullJid fullJid);
368
369        /**
370         * See {@link #isParentOf(Jid)}.
371         *
372         * @param domainBareJid the domain bare JID.
373         * @return true if this JID is a parent of the given JID.
374         */
375        boolean isParentOf(DomainBareJid domainBareJid);
376
377        /**
378         * See {@link #isParentOf(Jid)}.
379         *
380         * @param domainFullJid the domain full JID.
381         * @return true if this JID is a parent of the given JID.
382         */
383        boolean isParentOf(DomainFullJid domainFullJid);
384
385        /**
386         * Return the downcasted instance of this Jid. This method is unsafe, make sure to check that this is actually of the type of are casting to.
387         *
388         * @param jidClass the class of JID to downcast too.
389         * @param <T> the Jid type to downcast to.
390         * @return the downcasted instanced of this
391         * @throws ClassCastException if this JID is not assignable to the type T.
392         */
393        <T extends Jid> T downcast(Class<T> jidClass) throws ClassCastException;
394
395        /**
396         * Compares the given CharSequence with this JID. Returns true if {@code equals(charSequence.toString()} would
397         * return true.
398         *
399         * @param charSequence the CharSequence to compare this JID with.
400         * @return true if if {@code equals(charSequence.toString()} would return true.
401         * @see #equals(String)
402         */
403        @SuppressWarnings("NonOverridingEquals")
404        boolean equals(CharSequence charSequence);
405
406        /**
407         * Compares the given String wit this JID.
408         * <p>
409         * Returns true if {@code toString().equals(string)}, that is if the String representation of this JID matches the given string.
410         * </p>
411         *
412         * @param string the String to compare this JID with.
413         * @return true if {@code toString().equals(string)}.
414         */
415        @SuppressWarnings("NonOverridingEquals")
416        boolean equals(String string);
417
418        /**
419         * Returns the canonical String representation of this JID. See {@link String#intern} for details.
420         * 
421         * @return the canonical String representation.
422         */
423        String intern();
424}