|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objecttigase.server.Packet
public class Packet
Objects of this class carry a single XMPP packet (stanza). The XMPP stanza is carried as an XML element in DOM structure by the Packet object which contains some extra information and convenience methods to quickly access the most important stanza information.
The stanza is accessible directly through thegetElement()
method
and then it can be handles as an XML object. Packet
object and carried the
stanza Element
is not unmodifiable it should be treated as such. This
particular Packet
can be processed concurrently at the same time in
different components or plugins of the Tigase server. Modifying it may lead to
unexpected and hard to diagnoze behaviours. Every time you want to change or
update the object you should obtaina a copy of it using one of the utility methods:
copyElementOnly()
, swapFromTo(...)
,
errorResult(...)
, okResult(...)
,
swapStanzaFromTo(...)
There are no public constructors for the class, instead you have to use factory
methods: packetInstance(...)
which return instance of one of the
classes: Iq
, Message
or Presence
.
While creating a new Packet
instance JIDs are parsed and processed
through the stringprep. Hence some of the factory methods may throw
TigaseStringprepException
exception. You can avoid this by using
the methods which accept preparsed JIDs. Reusing preparsed JIDs is highly
recommended.
There are 3 kinds of addresses available from the Packet
object:
PacketFrom/To, StanzaFrom/To and From/To.Packet
methods.PacketFrom
address to address of your component
(getComponentId()
) address is that if there is a packet delivery problem
it will be returned back to the sender with apropriate error message.Packet
using PacketFrom/To addresses if
they are null then Stanza addresses are used instead. So these are just convenience
methods which allow avoiding extra IFs
in the program code and also
save some CPU cycles.
Created: Tue Nov 22 07:07:11 2005
Field Summary | |
---|---|
protected tigase.xml.Element |
elem
|
static boolean |
FULL_DEBUG
The variable control whether the toStringSecure() hides all the CData information from stanzas printed to logs or logs the full, detailed stanza content. |
Constructor Summary | |
---|---|
protected |
Packet(tigase.xml.Element elem)
A constructor creating the Packet instance. |
protected |
Packet(tigase.xml.Element elem,
tigase.xmpp.JID stanzaFrom,
tigase.xmpp.JID stanzaTo)
A constructor creating the Packet instance. |
Method Summary | |
---|---|
Packet |
copyElementOnly()
copyElementOnly method creates a copy of the packet with stanza
information copied only. |
String |
debug()
Method returns a string representation of all the data enclosed by the Packet intance. |
Packet |
errorResult(String errorType,
Integer errorCode,
String errorCondition,
String errorText,
boolean includeOriginalXML)
Method returns a modified copy of the Packet with its stanza as
stanza error used for reporting errors. |
String |
getAttribute(String key)
A convenience method for accessing stanza top element attributes. |
String |
getAttribute(String path,
String key)
A convenience method for accessing stanza top level or any of it's children attribute. |
Command |
getCommand()
The method alwats returns NULL. |
String |
getElemCData()
Method return character data for the stanza top element. |
String |
getElemCData(String xmlPath)
Method returns character data from the enclosed stanza for a given stanza element or child pointed by the xmlPath parameter. |
List<tigase.xml.Element> |
getElemChildren(String xmlPath)
Method returns a list of all XML children from the enclosed stanza for a given stanza element or child pointed by the xmlPath parameter. |
tigase.xml.Element |
getElement()
Method returns the stanza XML element in DOM format. |
String |
getElemFrom()
Deprecated. use getStanzaFrom() instead. |
String |
getElemName()
Cnvenience method for retrieving the stanza top element name. |
String |
getElemTo()
Deprecated. use getStanzaTo() instead |
String |
getErrorCondition()
Method parses the stanza and returns the error condition if there is any. |
tigase.xmpp.JID |
getFrom()
Returns the packet source address. |
tigase.xmpp.JID |
getPacketFrom()
Returns the packet internal source address. |
tigase.xmpp.JID |
getPacketTo()
Returns the packet internal destination address. |
Permissions |
getPermissions()
Method returns permissions set of the user who has sent the packet. |
Priority |
getPriority()
Method returns the packet priority, |
Set<String> |
getProcessorsIds()
Method returns a set of all processor IDs which processed the packet. |
tigase.xmpp.JID |
getStanzaFrom()
Method returns source address of rhe stanza enclosed by this packet. |
String |
getStanzaId()
Method returns the stanza ID if set. |
tigase.xmpp.JID |
getStanzaTo()
Method returns destinaion address of rhe stanza enclosed by this packet. |
tigase.xmpp.JID |
getTo()
Returns the packet destination address. |
StanzaType |
getType()
Method returns the stanza type parsed from the top XML element of the enclosed stanza. |
String |
getXMLNS()
Returns the enclosed stanza top element XMLNS. |
void |
initVars()
The method allows for resyncing/parsing stanza JIDs stored in the packet with the attributes of the stanza if they have been changed for any reason. |
void |
initVars(tigase.xmpp.JID stanzaFrom,
tigase.xmpp.JID stanzaTo)
The method allows for resyncing stanza JIDs stored in the packet with the attributes of the stanza if they have been changed for any reason. |
boolean |
isCommand()
The method checks whether the stanza enclosed by this Packet
instance is an ad-hoc command. |
boolean |
isElement(String name,
String xmlns)
The method checks wherher the enclosed stanza is a speciifc XML element. |
boolean |
isRouted()
Method determines whether the stanza represents so called routed packet. |
boolean |
isServiceDisco()
A convenience method which checks whether the enclosed stanza is a service discovery query. |
boolean |
isXMLNS(String elementPath,
String xmlns)
The method checks whether the enclosed stanza contains an XML element and XML child element for a given element path and xmlns. |
Packet |
okResult(tigase.xml.Element includeXML,
int originalXML)
Method returns a modified copy of the Packet with its stanza as
stanza result used for reporting IQ stanza results. |
Packet |
okResult(String includeXML,
int originalXML)
Method returns a modified copy of the Packet with its stanza as
stanza result used for reporting IQ stanza results. |
static Packet |
packetInstance(tigase.xml.Element elem)
The method returns Packet instance. |
static Packet |
packetInstance(tigase.xml.Element elem,
tigase.xmpp.JID stanzaFrom,
tigase.xmpp.JID stanzaTo)
The method returns Packet instance. |
static Packet |
packetInstance(String el_name,
String from,
String to,
StanzaType type)
The method creates XML stanza from given parameters and returns Packet instance for this XML stanza. |
Packet |
packRouted()
Returns a new Packet instance with stanza routed
which means an original stanza has been enclosed inside a route
XML element which contains additional information taken from
Packet packet instance internal attributes. |
void |
processedBy(String id)
The method marks that the packet has been processed by a packet processor with a given ID. |
void |
setPacketFrom(tigase.xmpp.JID from)
The method sets a source address for the Packet instance. |
void |
setPacketTo(tigase.xmpp.JID to)
The method sets a destination address for the Packet instance. |
void |
setPermissions(Permissions perm)
The method sets permissions for the packet of a user who sent the stanza. |
void |
setPriority(Priority priority)
The method sets the packet priority. |
Packet |
swapElemFromTo()
Deprecated. Use swapStanzaFromTo() instead. |
Packet |
swapElemFromTo(StanzaType type)
Deprecated. Use swapStanzaFromTo() instead. |
Packet |
swapFromTo()
Creates a new Packet instance with swapped packet source and
destination addresses. |
Packet |
swapFromTo(tigase.xml.Element el,
tigase.xmpp.JID stanzaFrom,
tigase.xmpp.JID stanzaTo)
The method creates a new instance of the Packet class with the
packet source and destination addresses swapped and sets the given stanza
element plus source and destination addresses for the new stanza. |
Packet |
swapStanzaFromTo()
The method creates a new Packet instance with a stanza copy
with swapped source and destination addresses. |
Packet |
swapStanzaFromTo(StanzaType type)
The method creates a new Packet instance with a stanza copy
with swapped source and destination addresses and the given type set. |
String |
toString()
The method converts the Packet instance to a String
representation. |
String |
toString(boolean secure)
Is a convenience method which allows you to call always the same method but parametrize (configure) whether you want to get a secure packet string representation or full representation. |
String |
toStringSecure()
The method returns a String representation of the packet with
all CData content replaced with text: "CData size: NN". |
Packet |
unpackRouted()
The method unpacks the original packet and stanza from route
stanza. |
boolean |
wasProcessed()
The method determines whether the packet has been processed by any of the packet processors. |
boolean |
wasProcessedBy(String id)
The method checks whether the packet has been processed by a packet processor with the specified ID. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static boolean FULL_DEBUG
'packet.debug.full'
to 'true'
.
protected tigase.xml.Element elem
Constructor Detail |
---|
protected Packet(tigase.xml.Element elem) throws tigase.util.TigaseStringprepException
Packet
instance. This is not part of
the public API, please use packetInstance(...)
instead.
elem
- is XML element with a single XMPP stanza.
tigase.util.TigaseStringprepException
- exception is thrown if the stanza source or
destination address stringprep processing failed.protected Packet(tigase.xml.Element elem, tigase.xmpp.JID stanzaFrom, tigase.xmpp.JID stanzaTo)
Packet
instance. This is not part of
the public API, please use packetInstance(...)
instead.
elem
- is XML element with a single XMPP stanza.stanzaFrom
- is a source JID address of the stanza passed as the
contructor parameter.stanzaTo
- is a destination JID address of the stanza passed as the
constructor parameter.Method Detail |
---|
public static Packet packetInstance(tigase.xml.Element elem) throws tigase.util.TigaseStringprepException
Packet
instance.
More specificly it returns instance of one of the following classes: Iq
,
Message
or Presence
. It takes stanza XML element
as an arguments, parses some the most commonly used data and created an object.
Preparsed information are: stanza from/to addresses, stanza id, type and presets
the Packet
priority.
If there is a stringprep processing error for either the stanza source or destination
address TigaseStringprepException
exception is thrown.
elem
- is a stanza XML Element
Packet
instance, more specificly instance of one of the
following classes: Iq
, Message
or Presence
.
tigase.util.TigaseStringprepException
- if there is stanza from or to address parsing
error.public static Packet packetInstance(tigase.xml.Element elem, tigase.xmpp.JID stanzaFrom, tigase.xmpp.JID stanzaTo)
Packet
instance.
More specificly it returns instance of one of the following classes: Iq
,
Message
or Presence
. It takes stanza XML element
as an arguments and preparsed stanza from and to addresses. The method
parses some other, the most commonly used data and created an object.
Preparsed information are: stanza id, type and presets the Packet
priority.
This method does not parses stanza from and stanza to address from the given XML
document, hence it does not throw TigaseStringprepException
. Even
though reusing parsed from and to address is highly recommended an extra care
is needed to pass correct parameters as stanza JIDs or the packet may be
incorrectly routed or processed.
elem
- is the stanza XML Element
stanzaFrom
- is a preparsed JID
instance from the given stanza
XML element.stanzaTo
- is a preparsed JID
instance from the given stanza
XML element.
Packet
instance, more specificly instance of one of the
following classes: Iq
, Message
or Presence
.public static Packet packetInstance(String el_name, String from, String to, StanzaType type) throws tigase.util.TigaseStringprepException
Packet
instance for this XML stanza.
More specificly it returns instance of one of the following classes: Iq
,
Message
or Presence
.
The method first builds an XML stanza from given parameters: element name,
from and to addresses and stanza type, then it creates a Packet instance for the
stanza. It also runs all the parsing and stringprep processing, hence it throws
an exception if any error is found.
el_name
- XML stanza elemen name as String
.from
- is the stanza from address as String
to
- is the stanza to address as String
.type
- is one of the stanza types: set, get,
result, .... as StanzaType
instance.
Packet
instance, more specificly instance of one of the
following classes: Iq
, Message
or Presence
.
tigase.util.TigaseStringprepException
- if there is stanza from or to address parsing
error.public Packet copyElementOnly()
copyElementOnly
method creates a copy of the packet with stanza
information copied only. The Packet
specific information stays
blank (NULL): (packetFrom, packetTo, etc...).
This method should be used to obtain a copy of the packet without setting
packet specific fields (packetFrom or packetTo). The method reuses preparsed
stanza JIDs and does not throw any exception.
public String debug()
Packet
intance. All stanza XML element and all fields are converted
to the String
representation for debugging. Please note, this may
be resources consuming process so use it only when experiencing problems with
Packet
content.
String
representation of the packet with all its fields.public Packet errorResult(String errorType, Integer errorCode, String errorCondition, String errorText, boolean includeOriginalXML)
Packet
with its stanza as
stanza error used for reporting errors. It is recommended not to use this
method directly as there is a utility class which makes generating error responses
much simpler. An example call (which uses this method underneath) looks like this
example:
import tigase.xmpp.Authorization; Authorization.BAD_REQUEST.getResponseMessage(packet, "Error message", true/false);This utility class and it's method acts not only as a convenience but also provides some additional checking and control.
errorType
- is a String
representation of the error type defined
in the XMPP RFC-3920.errorCode
- is an integer error code defined in the XMPP RFC for backward
compatibility with old Jabber implementatons.errorCondition
- is a String
representation of the error condition
defined in the XMPP RFC-3920.errorText
- human readable error message.includeOriginalXML
- a boolean parameter indicating whether stanza top element
children should be included in the error message.
Packet
instance with an error type stanza which
is a response to this Packet
instance.public String getAttribute(String key)
packet.getElement().getAttribute(key);
key
- is an attribute key.
public String getAttribute(String path, String key)
packet.getElement().getAttribute(xmlPath, key);
path
- is XML path for the stanza element or stanza child for which attribute
is retrieved.key
- is an attribute key.
public Command getCommand()
Iq
class
where it returns a command identifier if the iq stanza represnts an
ad-hoc command. It is provided here is a convenience so the developer does not
have to cast the packet to IQ before retrieving the command id.
public String getElemCData(String xmlPath)
xmlPath
parameter.
This call is equal to the call:
packet.getElement().getCData(xmlPath);
xmlPath
- is an XML path to the stanza element for which CData is retrieved.
public String getElemCData()
packet.getElement().getCData();
public List<tigase.xml.Element> getElemChildren(String xmlPath)
xmlPath
parameter.
This call is equal to the call:
packet.getElement().getChildren(xmlPath);
xmlPath
- is an XML path to the stanza element for which children are
retrieved.
@Deprecated public String getElemFrom()
String
representation of the stanza source address.
Use of this method is not recommended, the API is depreciated in favor of API
operating on JID
class.
String
representation of the stanza source address or NULL
if the source address has not been set.public String getElemName()
packet.getElement().getName();
@Deprecated public String getElemTo()
String
representation of the stanza destination
address.
Use of this method is not recommended, the API is depreciated in favor of API
operating on JID
class.
String
representation of the stanza destination address or
NULL if the destination address has not been set..public tigase.xml.Element getElement()
public String getErrorCondition()
public tigase.xmpp.JID getFrom()
return (packetFrom != null) ? packetFrom : stanzaFrom;
JID
instance of the packet source address or NULL if
neither the packet source address is set nor the stanza source address is set.public tigase.xmpp.JID getPacketFrom()
JID>/code> instance of the packet internal source address or
NULL if the packet internal source address has not been set
public tigase.xmpp.JID getPacketTo()
JID>/code> instance of the packet internal destination address or
NULL if the packet internal destination address has not been set.
public Permissions getPermissions()
public Priority getPriority()
public Set<String> getProcessorsIds()
Set
of stanza processor IDs which handled the packet.public tigase.xmpp.JID getStanzaFrom()
JID
instance of the stanza source address or NULL if the
source address has not been set for the stanza.public String getStanzaId()
String
representation of the stanza ID or NULL if the ID has
not been set for the stanza.public tigase.xmpp.JID getStanzaTo()
JID
instance of the stanza destination address or NULL if
the destination address has not been set for the stanza.public tigase.xmpp.JID getTo()
return (packetTo != null) ? packetTo : stanzaTo;
JID
instance of the packet destination address or NULL if
neither the packet destination address is set nor the stanza destination address
is set.public StanzaType getType()
StanzaType
instance of the stanza type parsed from the
top XML element of the enclosed stanza or NULL of the type has not been set.public String getXMLNS()
packet.getElement().getXMLNS();
String
instance of the stanza top element XMLNS.public void initVars(tigase.xmpp.JID stanzaFrom, tigase.xmpp.JID stanzaTo)
stanzaFrom
- is a parsed source address JID from the stanza enclosed by this
packet.stanzaTo
- is a parsed destination address JID from the stanza enclosed by
this packet.public void initVars() throws tigase.util.TigaseStringprepException
tigase.util.TigaseStringprepException
- if the stringprep error occurs during the stanza
JIDs parsing.public boolean isCommand()
Packet
instance is an ad-hoc command.
This is a generic method which in fact always returns false
. It
is overwritten in the Iq
class where the real checking is
performed. This class has been provided as a convenience method to perform
the check without a need for casting the Packet
instance to
the Iq
class.
boolean
value true
if the stanza is
an ad-hoc command and false
otherwise.public boolean isElement(String name, String xmlns)
return packet.getElement().getName() == name && packet.getElement().getXMLNS() == xmlns;
name
- is a String
representing the XML element name.xmlns
- is a String
representing the XML xmlns value.
public boolean isRouted()
boolean
value of true
if the packet is
routed and false
otherwise.public boolean isServiceDisco()
false
. It
is overwritten in the Iq
class where the real checking is
performed. This class has been provided as a convenience method to perform
the check without a need for casting the Packet
instance to
the Iq
class.
boolean
value true
if the stanza is
a a service discovery query and false
otherwise.public boolean isXMLNS(String elementPath, String xmlns)
elementPath
is directory path like string.
elementPath
- is a String
value which represents XML
element to a desired child element.xmlns
- is a String
value which represents XML XMLNS.
public Packet okResult(String includeXML, int originalXML)
Packet
with its stanza as
stanza result
used for reporting IQ stanza results.
The method preserves all the attributes of the original stanza, swaps stanza
source and destination addresses and can optionally add more child XML
elements and can preserve existing children elements up to given depth.
includeXML
- is an XML content serialized to String
or just
character data as String
which has to be added to response
stanza.originalXML
- parameter specified whether and if so to what depth the
original stanza child elements have to be preserved in the response packet.
Packet
instance with an OK (result) type stanza
which is a response to this Packet
instance.public Packet okResult(tigase.xml.Element includeXML, int originalXML)
Packet
with its stanza as
stanza result
used for reporting IQ stanza results.
The method preserves all the attributes of the original stanza, swaps stanza
source and destination addresses and can optionally add more child XML
elements and can preserve existing children elements up to given depth.
includeXML
- is an XML content which has to be added to the response
stanza.originalXML
- parameter specified whether and if so to what depth the
original stanza child elements have to be preserved in the response packet.
Packet
instance with an OK (result) type stanza
which is a response to this Packet
instance.public Packet packRouted()
Packet
instance with stanza routed
which means an original stanza has been enclosed inside a route
XML element which contains additional information taken from
Packet
packet instance internal attributes.
Packet
instance with route
stanza.public void processedBy(String id)
id
- is a String
instance of the packet processer identifier.public void setPacketFrom(tigase.xmpp.JID from)
Packet
instance.
from
- is a JID
instance of the packet new source address.public void setPacketTo(tigase.xmpp.JID to)
Packet
instance.
to
- is a JID
instance of the packet new destination
address.public void setPermissions(Permissions perm)
perm
- is Permissions
instance of the stanza sender
permissions calculated by the session manager.public void setPriority(Priority priority)
priority
- os a new Priority
instance set for the packet.@Deprecated public Packet swapElemFromTo()
swapStanzaFromTo()
instead.
swapStanzaFromTo()
instead.
@Deprecated public Packet swapElemFromTo(StanzaType type)
swapStanzaFromTo()
instead.
swapStanzaFromTo()
instead.
type
- a new stanza type which has to be set to the generated
stanza copy.
public Packet swapFromTo(tigase.xml.Element el, tigase.xmpp.JID stanzaFrom, tigase.xmpp.JID stanzaTo)
Packet
class with the
packet source and destination addresses swapped and sets the given stanza
element plus source and destination addresses for the new stanza.
This method gives you slightly more flexibility as you can set any source
and destination address for the new stanza.
This method is rarely used in packet processors which don't sent a simple
"ok result" response. Some data flow requires a completely new packet
to be send as a response to the original call, but the response has to be
delivered to the original sends. As an example are the SASL authentication
and TLS handshaking.
el
- is an XML element set for the new packet.stanzaFrom
- is the stanza source addressstanzaTo
- is the stanza destination address
Packet
instance.public Packet swapFromTo()
Packet
instance with swapped packet source and
destination addresses. Please note the new packet contains unchanged copy of the
original stanza. Stanza source and destination addresses are no swapped.
Packet>/code> instance.
public Packet swapStanzaFromTo()
Packet
instance with a stanza copy
with swapped source and destination addresses. The packet source and
destination addresses are set to null.
Packet
instance.public Packet swapStanzaFromTo(StanzaType type)
Packet
instance with a stanza copy
with swapped source and destination addresses and the given type set.
The packet source and destination addresses are set to null.
type
- is a new type for the stanza copy to set.
Packet
instance.public String toString()
Packet
instance to a String
representation. The stanza XML element is presented as the string and all packet
attributes are also added to the string.
The method is for a debugging purposes to log the whole packet content to
the debug file for further analysis. It is recommended to use
toStringSecure()
instead as it removes all the CData from the
stanza avoiding exposing user chat message content. The secure method
also preserves you from flooding your log files in case of a huge chunks of
data are sent in packets (user photos in vCards or files).
toString
in class Object
String
representation of the packet instance.public String toString(boolean secure)
secure
- parameter specifies whether the secure packet representation
should be returned (true
value) or the full one
(false
).
String
representation of the packet instance.public String toStringSecure()
String
representation of the packet with
all CData content replaced with text: "CData size: NN". This is a
preferable method to log the packets for debuging purposes.
String
representation of the packet instance.public Packet unpackRouted() throws tigase.util.TigaseStringprepException
route
stanza.
This is the opposite action to the packRouted()
method.
Packet
class with unpacket
packet and stanza from route
stanza.
tigase.util.TigaseStringprepException
- if there was a problem with addresses
stringprep processing.public boolean wasProcessed()
processedBy(...)
on the packet.
boolean
value of true
of the packet was
processed by any processor and false
otherwise.public boolean wasProcessedBy(String id)
id
- is a String
instance of the packet processor identifier.
boolean
value of true
of the packet was
processed by a processor with specified ID and false
otherwise.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |