org.jxmpp.jid.Jid Maven / Gradle / Ivy
/**
*
* Copyright © 2014-2020 Florian Schmaus
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jxmpp.jid;
import java.io.Serializable;
import org.jxmpp.jid.parts.Domainpart;
import org.jxmpp.jid.parts.Localpart;
import org.jxmpp.jid.parts.Resourcepart;
/**
* An XMPP address, also known as JID (formerly for "Jabber Identifier"), which acts as globally unique address
* within the XMPP network.
*
* JIDs are created from {@link String} or {@link CharSequence} with the {@link org.jxmpp.jid.impl.JidCreate} utility.
*
*
*
* Jid jid = JidCreate.from("[email protected]/balcony");
* EntityBareJid bareJid = JidCreate.entityBareFrom("[email protected]");
*
*
* This is the super interface for all JID types, which are constructed from two dimensions: Bare/Full and
* Domain/Entity. Every JID consists at least of a {@link Domainpart}. Bare JID types do not come with a
* {@link Resourcepart}, full JID types always have a {@link Resourcepart}. Domain JID types do not possess a
* {@link Localpart}, whereas entity JID types always do.
*
*
* The following table shows a few examples of JID types.
*
*
* XMPP Address Types
*
* Example
* Type
*
*
* example.org{@link DomainBareJid}
*
*
* example.org/resource{@link DomainFullJid}
*
*
* [email protected]{@link EntityBareJid}
*
*
* [email protected]/resource{@link EntityFullJid}
*
*
*
* You can retrieve the escaped String representing the Jid with {@link #toString()} or the unescaped String of the JID
* with {@link #asUnescapedString()}.
*
* URL Encoded JIDs
*
* 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.
* You can retrieve this information using {@link #asUrlEncodedString()}. The JidCreate API provides methods to create
* JIDs from URL encoded Strings like {@link org.jxmpp.jid.impl.JidCreate#fromUrlEncoded(CharSequence)}.
*
*
*
* @see RFC 6120 (XMPP: Core) § 2.1 Global Addresses
* @see RFC 6122 (XMPP: Address Format) § 2.1
* Fundamentals
*/
public interface Jid extends Comparable, CharSequence, Serializable {
/**
* Get the {@link Domainpart} of this Jid.
*
* @return the domainpart.
*/
Domainpart getDomain();
/**
* Returns the String representation of this JID.
*
* @return the String representation of this JID.
*/
@Override
String toString();
/**
* Return the unescaped String representation of this JID.
*
* Since certain Unicode code points are disallowed in the localpart of a JID by the required stringprep profile,
* those need to get escaped when used in a real JID. The unescaped representation of the JID is only for
* presentation to a human user or for gatewaying to a non-XMPP system.
*
* For example, if the users inputs {@code 'at&t [email protected]'}, the escaped real JID created with
* {@link org.jxmpp.jid.impl.JidCreate} will be {@code 'at\26t\[email protected]'}, which is what
* {@link Jid#toString()} will return. But {@link Jid#asUnescapedString()} will return again
* {@code 'at&t [email protected]'}.
*
* @return the unescaped String representation of this JID.
*/
String asUnescapedString();
/**
* Get the URL encoded version of this JID.
*
* @return the URL encoded version of this JID.
* @since 0.7.0
*/
String asUrlEncodedString();
/**
* Check if this is a {@link EntityBareJid} or {@link EntityFullJid}.
*
* @return true if this is an instance of BareJid or FullJid.
*/
boolean isEntityJid();
/**
* Check if this is an instance of {@link EntityBareJid}.
*
* @return true if this is an instance of EntityBareJid
*/
boolean isEntityBareJid();
/**
* Check if this is an instance of {@link EntityFullJid}.
*
* @return true if this is an instance of EntityFullJid
*/
boolean isEntityFullJid();
/**
* Check if this is an instance of {@link DomainBareJid}.
*
* @return true if this is an instance of DomainBareJid
*/
boolean isDomainBareJid();
/**
* Check if this is an instance of {@link DomainFullJid}.
*
* @return true if this is an instance of DomainFullJid
*/
boolean isDomainFullJid();
/**
* Check if this is an instance of {@link EntityBareJid} or {@link DomainBareJid}.
*
* @return true if this is an instance of BareJid or DomainBareJid
*/
boolean hasNoResource();
/**
* Check if this is a Jid with a {@link Resourcepart}.
*
* @return true if this Jid has a resourcepart.
*/
boolean hasResource();
/**
* Check if this is a Jid with a {@link Localpart}.
*
* @return true if this Jid has a localpart.
*/
boolean hasLocalpart();
/**
* Return a JID created by removing the Resourcepart from this JID.
*
* @return this Jid without a Resourcepart.
*/
BareJid asBareJid();
/**
* Convert this Jid to a {@link EntityBareJid} if possible.
*
* @return the corresponding {@link EntityBareJid} or null.
*/
EntityBareJid asEntityBareJidIfPossible();
/**
* Convert this Jid to a {@link EntityBareJid} or throw an {@code IllegalStateException} if this is not possible.
*
* @return the corresponding {@link EntityBareJid}.
*/
EntityBareJid asEntityBareJidOrThrow();
/**
* Convert this Jid to a {@link EntityFullJid} if possible.
*
* @return the corresponding {@link EntityFullJid} or null.
*/
EntityFullJid asEntityFullJidIfPossible();
/**
* Convert this Jid to a {@link EntityFullJid} or throw an {@code IllegalStateException} if this is not possible.
*
* @return the corresponding {@link EntityFullJid}.
*/
EntityFullJid asEntityFullJidOrThrow();
/**
* Convert this Jid to a {@link EntityJid} if possible.
*
* @return the corresponding {@link EntityJid} or null.
*/
EntityJid asEntityJidIfPossible();
/**
* Convert this Jid to a {@link EntityJid} or throw an {@code IllegalStateException} if this is not possible.
*
* @return the corresponding {@link EntityJid}.
*/
EntityJid asEntityJidOrThrow();
/**
* Convert this Jid to a {@link FullJid} if possible.
*
* @return the corresponding {@link FullJid} or null.
*/
FullJid asFullJidIfPossible();
/**
* Convert this Jid to a {@link FullJid} or throw an {@code IllegalStateException} if this is not possible.
*
* @return the corresponding {@link FullJid}.
*/
EntityFullJid asFullJidOrThrow();
/**
* Convert this Jid to a {@link DomainBareJid}.
*
* Note that it is always possible to convert a Jid to a DomainBareJid, since every Jid has a domain part.
*
*
* @return the corresponding DomainBareJid.
*/
DomainBareJid asDomainBareJid();
/**
* Convert this Jid to a {@link DomainFullJid} if possible.
*
* @return the corresponding DomainFullJid or null.
*/
DomainFullJid asDomainFullJidIfPossible();
/**
* Convert this Jid to a {@link DomainFullJid} or throw an {@code IllegalStateException} if this is not possible.
*
* @return the corresponding {@link DomainFullJid}.
*/
DomainFullJid asDomainFullJidOrThrow();
/**
* Get the resourcepart of this JID or null.
*
* If the JID is of form {@code } then this method returns 'resource'. If the JID no
* resourcepart, then null is returned.
*
*
* @return the resource of this JID or null.
*/
Resourcepart getResourceOrNull();
/**
* Get the resourcepart of this JID or return the empty resourcepart.
*
* If the JID is of form {@code } then this method returns 'resource'. If the JID no
* resourcepart, then {@link org.jxmpp.jid.parts.Resourcepart#EMPTY} is returned.
*
*
* @return the resource of this JID or the empty resourcepart.
*/
Resourcepart getResourceOrEmpty();
/**
* Get the resourcepart of this JID or throw an {@code IllegalStateException}.
*
* If the JID is of form {@code } then this method returns 'resource'. If the JID no
* resourcepart, then an {@code IllegalStateException} is thrown.
*
*
* @return the resource of this JID.
*/
Resourcepart getResourceOrThrow();
/**
* Get the localpart of this JID or null.
*
* If the JID is of form {@code } then this method returns 'localpart'. If the JID has no
* localpart, then null is returned.
*
*
* @return the localpart of this JID or null.
*/
Localpart getLocalpartOrNull();
/**
* Get the localpart of this JID or throw an {@code IllegalStateException}.
*
* If the JID is of form {@code } then this method returns 'localpart'. If the JID has no
* localpart, then null is returned.
*
*
* @return the localpart of this JID.
*/
Localpart getLocalpartOrThrow();
/**
* Check if this JID is the parent of another JID. The parent of relation is defined, under the
* precondition that the JID parts (localpart, domainpart and resourcepart) are equal, as follows:
*
* | this JID (parentOf) | other JID | result |
* |---------------------+---------------------+--------|
* | dom.example | dom.example | true |
* | dom.example | dom.example/res | true |
* | dom.example | [email protected] | true |
* | dom.example | [email protected]/res | true |
* | dom.example/res | dom.exmple | false |
* | dom.example/res | dom.example/res | true |
* | dom.example/res | [email protected] | false |
* | dom.example/res | [email protected]/res | false |
* | [email protected] | dom.example | false |
* | [email protected] | dom.example/res | false |
* | [email protected] | [email protected] | true |
* | [email protected] | [email protected]/res | true |
* | [email protected]/res | dom.example | false |
* | [email protected]/res | dom.example/res | false |
* | [email protected]/res | [email protected] | false |
* | [email protected]/res | [email protected]/res | true |
*
*
* @param jid
* the other JID to compare with
* @return true if this JID is a parent of the given JID.
*/
boolean isParentOf(Jid jid);
/**
* See {@link #isParentOf(Jid)}.
*
* @param bareJid the bare JID.
* @return true if this JID is a parent of the given JID.
*/
boolean isParentOf(EntityBareJid bareJid);
/**
* See {@link #isParentOf(Jid)}.
*
* @param fullJid the full JID.
* @return true if this JID is a parent of the given JID.
*/
boolean isParentOf(EntityFullJid fullJid);
/**
* See {@link #isParentOf(Jid)}.
*
* @param domainBareJid the domain bare JID.
* @return true if this JID is a parent of the given JID.
*/
boolean isParentOf(DomainBareJid domainBareJid);
/**
* See {@link #isParentOf(Jid)}.
*
* @param domainFullJid the domain full JID.
* @return true if this JID is a parent of the given JID.
*/
boolean isParentOf(DomainFullJid domainFullJid);
/**
* 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.
*
* @param jidClass the class of JID to downcast too.
* @param the Jid type to downcast to.
* @return the downcasted instanced of this
* @throws ClassCastException if this JID is not assignable to the type T.
*/
T downcast(Class jidClass) throws ClassCastException;
/**
* Compares the given CharSequence with this JID. Returns true if {@code equals(charSequence.toString()} would
* return true.
*
* @param charSequence the CharSequence to compare this JID with.
* @return true if if {@code equals(charSequence.toString()} would return true.
* @see #equals(String)
*/
@SuppressWarnings("NonOverridingEquals")
boolean equals(CharSequence charSequence);
/**
* Compares the given String wit this JID.
*
* Returns true if {@code toString().equals(string)}, that is if the String representation of this JID matches the given string.
*
*
* @param string the String to compare this JID with.
* @return true if {@code toString().equals(string)}.
*/
@SuppressWarnings("NonOverridingEquals")
boolean equals(String string);
/**
* Returns the canonical String representation of this JID. See {@link String#intern} for details.
*
* @return the canonical String representation.
*/
String intern();
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy