org.jxmpp.jid.Jid Maven / Gradle / Ivy
/**
*
* Copyright © 2014-2015 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 JID, which acts as globally unique address within the XMPP network.
*
* JIDs are created from Strings or CharSequences with the {@link org.jxmpp.jid.impl.JidCreate} utility.
*
* {@code
* Jid jid = JidCreate.from("[email protected]/balcony");
* BareJid bareJid = JidCreate.from("[email protected]");
* }
*
* This is the super interface for all JID types. Every JID consists at least of
* a {@link Domainpart}. You can retrieve the escaped String representing the Jid with {@link #toString()}
* or the unsecaped String of the JID with {@link #asUnescapedString()}.
*
* @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.
*/
public Domainpart getDomain();
/**
* Returns the String representation of this JID.
*
* @return the String representation of this JID.
*/
public 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.
*/
public String asUnescapedString();
/**
* Check if this is a {@link EntityBareJid} or {@link EntityFullJid}.
*
* @return true if this is an instance of BareJid or FullJid.
*/
public boolean isEntityJid();
/**
* Check if this is an instance of {@link EntityBareJid}.
*
* @return true if this is an instance of BareJid
*/
public boolean isEntityBareJid();
/**
* Check if this is an instance of {@link EntityFullJid}.
*
* @return true if this is an instance of FullJid
*/
public boolean isEntityFullJid();
/**
* Check if this is an instance of {@link DomainBareJid}.
*
* @return true if this is an instance of DomainBareJid
*/
public boolean isDomainBareJid();
/**
* Check if this is an instance of {@link DomainFullJid}.
*
* @return true if this is an instance of DomainFullJid
*/
public 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
*/
public boolean hasNoResource();
/**
* Check if this is a Jid with a {@link Resourcepart}.
*
* @return true if this Jid has a resourcepart.
*/
public boolean hasResource();
/**
* Check if this is a Jid with a {@link Localpart}.
*
* @return true if this Jid has a localpart.
*/
public boolean hasLocalpart();
/**
* Convert this Jid to a {@link EntityBareJid} if possible.
*
* @return the corresponding {@link EntityBareJid} or null.
*/
public EntityBareJid asEntityBareJidIfPossible();
/**
* Convert this Jid to a {@link EntityFullJid} if possible.
*
* @return the corresponding {@link EntityFullJid} or null.
*/
public EntityFullJid asEntityFullJidIfPossible();
/**
* Convert this Jid to a {@link EntityJid} if possible.
*
* @return the corresponding {@link EntityJid} or null.
*/
public EntityJid asEntityJidIfPossible();
/**
* Convert this Jid to a {@link FullJid} if possible.
*
* @return the corresponding {@link FullJid} or null.
*/
public FullJid asFullJidIfPossible();
/**
* 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.
*/
public DomainBareJid asDomainBareJid();
/**
* Convert this Jid to a {@link DomainFullJid} if possible.
*
* @return the corresponding DomainFullJid or null.
*/
public DomainFullJid asDomainFullJidIfPossible();
/**
* 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.
*/
public Resourcepart getResourceOrNull();
/**
* 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.
*/
public Localpart getLocalpartOrNull();
/**
* Return a JID created by removing the Resourcepart from this JID.
*
* @return this Jid without a Resourcepart.
*/
public Jid withoutResource();
/**
* 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.
*/
public 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.
*/
public 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.
*/
public 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.
*/
public 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.
*/
public 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 the Jid type to downcast to.
* @return the downcasted instanced of this
*/
public T downcast();
/**
* 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)
*/
public 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)}.
*/
public boolean equals(String string);
/**
* Returns the canonical String representation of this JID. See {@link String#intern} for details.
*
* @return the canonical String representation.
*/
public String intern();
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy