tigase.server

## Class Packet

- java.lang.Object
- - tigase.server.Packet

- Direct Known Subclasses:
    Iq, Message, Presence

      public class Packet
      extends Object

  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 the `getElement()` method and then it can be handles as an XML object.
  Please note! Even though the `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 diagnose behaviors. 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.
  Stanza addresses are the normal XMPP addresses parsed from the XML stanza and as a convenience are available through methods as JID objects. This is not only convenient to the developer but also this is important for performance reasons as parsing JID and processing it through stringprep is quite expensive operation so it is better to do it once and reuse the parsed objects. Please note that any of them can be null. Note also. You should avoid parsing stanza JIDs from the XML element in your code as this may impact the server performance. Reuse the JIDs provided from the `Packet` methods.
  Packet addresses are also JID objects but they may contain a different values from the Stanza addresses. These are the Tigase internal addresses used by the server and they usually contain Tigase component source and destination address. In most cases they are used between connection managers and session managers and can be ignored by other code. One advantage of setting `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.
  Simple From/To addresses contains values following the logic: If PacketFrom/To is not null then it contains PacketFrom/To values otherwise it contains StanzaFrom/To values. This is because the Tigase server tries always to deliver and process the `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
  Version:
    $Rev$
  Author:
    Artur Hefczyc

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CLIENT_XMLNS` Field description
    `protected Element` | `elem` Field description
    `static String` | `FROM_ATT` Field description
    `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.
    `static String` | `ID_ATT` Field description
    `static String` | `PERM_ATT` Field description
    `static String` | `PRIORITY_ATT` Field description
    `static String` | `TO_ATT` Field description
    `static String` | `TYPE_ATT` Field description
    `static String` | `XMLNS_ATT` Field description

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Packet(Element elem)` A constructor creating the `Packet` instance.
    `protected` | `Packet(Element elem, JID stanzaFrom, JID stanzaTo)` A constructor creating the `Packet` instance.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` instance.
    `static String` | `elemToString(Element el)` Method trims `Element` stanza to 1024 characters and returns String representation of the element
    `static String` | `elemToStringSecure(Element el)` Method trims `Element` stanza to 1024 characters and returns String representation of the element.
    `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)` Deprecated. Consider using `getAttributeStaticStr(java.lang.String)` instead.
    `String` | `getAttribute(String[] path, String key)` Deprecated. use `getAttributeStaticStr(java.lang.String[], java.lang.String)` instead, if possible, if not, contact us so we preserve the API.
    `String` | `getAttribute(String path, String key)` Deprecated. use `getAttributeStaticStr(java.lang.String[], java.lang.String)` instead, if possible, or `getAttribute(java.lang.String[], java.lang.String)`
    `String` | `getAttributeStaticStr(String key)` A convenience method for accessing stanza top element attributes.
    `String` | `getAttributeStaticStr(String[] path, String key)` A convenience method for accessing stanza top level or any of it's children attribute.
    `Command` | `getCommand()` The method always returns NULL.
    `String` | `getElemCData()` Method return character data for the stanza top element.
    `String` | `getElemCData(String xmlPath)` Deprecated. use `getElemCDataStaticStr(java.lang.String[])` instead, if possible, or `getElemCData(java.lang.String[])`
    `String` | `getElemCData(String[] xmlPath)` Deprecated. use `getElemCDataStaticStr(java.lang.String[])` instead, if possible, if not, contact us so we preserve the API.
    `String` | `getElemCDataStaticStr(String[] xmlPath)` Method returns character data from the enclosed stanza for a given stanza element or child pointed by the `xmlPath` parameter.
    `List<Element>` | `getElemChildren(String xmlPath)` Deprecated. use `getElemChildrenStaticStr(java.lang.String[])` instead, if possible, or `getElemChildren(java.lang.String[])`.
    `List<Element>` | `getElemChildren(String[] xmlPath)` Deprecated. use `getElemChildrenStaticStr(java.lang.String[])` instead, if possible, if not, contact us so we preserve the API.
    `List<Element>` | `getElemChildrenStaticStr(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.
    `Element` | `getElement()` Method returns the stanza XML element in DOM format.
    `String` | `getElemFrom()` Deprecated. use getStanzaFrom() instead.
    `String` | `getElemName()` Convenience method for retrieving the stanza top element name.
    `String` | `getElemTo()` Deprecated. use getStanzaTo() instead
    `protected String[]` | `getElNameErrorPath()` A convenience method to provide XML path as `String[]` to error element.
    `String` | `getErrorCondition()` Method parses the stanza and returns the error condition if there is any.
    `JID` | `getFrom()` Returns the packet source address.
    `JID` | `getPacketFrom()` Returns the packet internal source address.
    `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.
    `Set<String>` | `getSkippedProcessorsIds()` Method returns a set of all processor IDs which skipped processing packets.
    `JID` | `getStanzaFrom()` Method returns source address of the stanza enclosed by this packet.
    `String` | `getStanzaId()` Method returns the stanza ID if set.
    `JID` | `getStanzaTo()` Method returns destination address of the stanza enclosed by this packet.
    `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 re-syncing/parsing stanza JIDs stored in the packet with the attributes of the stanza if they have been changed for any reason.
    `void` | `initVars(JID stanzaFrom, JID stanzaTo)` The method allows for re-syncing 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 whether the enclosed stanza is a specific 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)` Deprecated. use `isXMLNSStaticStr(String[], String)` instead, if possible, if not contact us so we preserve the API.
    `boolean` | `isXMLNS(String elementPath, String xmlns)` Deprecated. use `isXMLNSStaticStr(String[], String)` instead, if possible, or `isXMLNS(String[], String)`
    `boolean` | `isXMLNSStaticStr(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.
    `void` | `notProcessedBy(String id)` The method marks that the packet has NOT been processed by a packet processor with a given ID.
    `Packet` | `okResult(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(Element elem)` The method returns `Packet` instance.
    `static Packet` | `packetInstance(Element elem, JID stanzaFrom, 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(JID from)` The method sets a source address for the `Packet` instance.
    `void` | `setPacketTo(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.
    `void` | `setXMLNS(String xmlns)` Method allows to set-force XMLNS for the element.
    `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(Element el, JID stanzaFrom, 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()` Provides human-readable string presentation of the `Packet` object.
    `String` | `toString(boolean secure)` Is a convenience method which allows you to call always the same method but change (configure) whether you want to get a secure packet string representation or full representation.
    `String` | `toStringFull()` The method converts the `Packet` instance to a `String` 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.
    `boolean` | `wasSkipped()` The method determines whether the packet was directed to processing by any packet processor, but it wasn't processed by them because of internal queue full.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### CLIENT_XMLNS

          public static final String CLIENT_XMLNS

      Field description
      See Also:
        Constant Field Values

    - #### FROM_ATT

          public static final String FROM_ATT

      Field description
      See Also:
        Constant Field Values

    - #### ID_ATT

          public static final String ID_ATT

      Field description
      See Also:
        Constant Field Values

    - #### PERM_ATT

          public static final String PERM_ATT

      Field description
      See Also:
        Constant Field Values

    - #### PRIORITY_ATT

          public static final String PRIORITY_ATT

      Field description
      See Also:
        Constant Field Values

    - #### TO_ATT

          public static final String TO_ATT

      Field description
      See Also:
        Constant Field Values

    - #### TYPE_ATT

          public static final String TYPE_ATT

      Field description
      See Also:
        Constant Field Values

    - #### XMLNS_ATT

          public static final String XMLNS_ATT

      Field description
      See Also:
        Constant Field Values

    - #### FULL_DEBUG

          public 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. By default the variable is set to 'false' to protect users' privacy and not reveal chat content. This is the value to be used in all production/live systems. For the debug purposes on the test or development system it can be set to 'true' to help diagnose run-time problems.
      You can change value of the field by setting system property: `'packet.debug.full'` to `'true'`.

    - #### elem

          protected Element elem

      Field description

  - ### Constructor Detail

    - #### Packet

          protected Packet(Element elem)
                    throws TigaseStringprepException

      A constructor creating the `Packet` instance. This is not part of the public API, please use `packetInstance(...)` instead.
      Parameters:
        `elem` - is XML element with a single XMPP stanza.
      Throws:
        `TigaseStringprepException` - exception is thrown if the stanza source or destination address stringprep processing failed.

    - #### Packet

          protected Packet(Element elem,
                           JID stanzaFrom,
                           JID stanzaTo)

      A constructor creating the `Packet` instance. This is not part of the public API, please use `packetInstance(...)` instead.
      Parameters:
        `elem` - is XML element with a single XMPP stanza.
        `stanzaFrom` - is a source JID address of the stanza passed as the constructor parameter.
        `stanzaTo` - is a destination JID address of the stanza passed as the constructor parameter.

  - ### Method Detail

    - #### elemToString

          public static String elemToString(Element el)

      Method trims `Element` stanza to 1024 characters and returns String representation of the element
      Parameters:
        `el` - Element which should be converted
      Returns:

    - #### elemToStringSecure

          public static String elemToStringSecure(Element el)

      Method trims `Element` stanza to 1024 characters and returns String representation of the element. This version uses secure representation of CData of the elements.
      Parameters:
        `el` - Element which should be converted
      Returns:

    - #### packetInstance

          public static Packet packetInstance(Element elem)
                                       throws TigaseStringprepException

      The method returns `Packet` instance. More specifically 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. Pre-parsed 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.
      Parameters:
        `elem` - is a stanza XML `Element`
      Returns:
        a `Packet` instance, more specifically instance of one of the following classes: `Iq`, `Message` or `Presence`.
      Throws:
        `TigaseStringprepException` - if there is stanza from or to address parsing error.

    - #### packetInstance

          public static Packet packetInstance(Element elem,
                                              JID stanzaFrom,
                                              JID stanzaTo)

      The method returns `Packet` instance. More specifically it returns instance of one of the following classes: `Iq`, `Message` or `Presence`. It takes stanza XML element as an arguments and pre-parsed stanza from and to addresses. The method parses some other, the most commonly used data and created an object. Pre-parsed 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.
      Parameters:
        `elem` - is the stanza XML `Element`
        `stanzaFrom` - is a pre-parsed `JID` instance from the given stanza XML element.
        `stanzaTo` - is a pre-parsed `JID` instance from the given stanza XML element.
      Returns:
        a `Packet` instance, more specifically instance of one of the following classes: `Iq`, `Message` or `Presence`.

    - #### packetInstance

          public static Packet packetInstance(String el_name,
                                              String from,
                                              String to,
                                              StanzaType type)
                                       throws TigaseStringprepException

      The method creates XML stanza from given parameters and returns `Packet` instance for this XML stanza. More specifically 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.
      Parameters:
        `el_name` - XML stanza element 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.
      Returns:
        a `Packet` instance, more specifically instance of one of the following classes: `Iq`, `Message` or `Presence`.
      Throws:
        `TigaseStringprepException` - if there is stanza from or to address parsing error.

    - #### copyElementOnly

          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.
      Returns:
        a new copy of the packet with packet specific fields set to NULL.

    - #### debug

          public String debug()

      Method returns a string representation of all the data enclosed by the `Packet` instance. 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.
      Returns:
        `String` representation of the packet with all its fields.

    - #### errorResult

          public 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. 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.
      Parameters:
        `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 implementations.
        `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.
      Returns:
        a new `Packet` instance with an error type stanza which is a response to this `Packet` instance.

    - #### getAttribute

          @Deprecated
          public String getAttribute(String key)

      Deprecated. Consider using `getAttributeStaticStr(java.lang.String)` instead.
      A convenience method for accessing stanza top element attributes. This call is equal to the call:

           packet.getElement().getAttribute(key);

      Parameters:
        `key` - is an attribute key.
      Returns:
        an attribute value or NULL if there is no such attribute.

    - #### getAttributeStaticStr

          public String getAttributeStaticStr(String key)

      A convenience method for accessing stanza top element attributes. This call is equal to the call:

           packet.getElement().getAttribute(key);

      Parameters:
        `key` - is an attribute key.
      Returns:
        an attribute value or NULL if there is no such attribute.

    - #### getAttributeStaticStr

          public String getAttributeStaticStr(String[] path,
                                              String key)

      A convenience method for accessing stanza top level or any of it's children attribute. This call is equal to the call:

           packet.getElement().getAttribute(xmlPath, key);

      Please note! This method can only be used with static strings or with strings processed through `String.intern()` call. It uses "==" for string comparison for performance reasons. If you pass dynamically built `String[]` to the method call, use `getAttribute(java.lang.String[], java.lang.String)` instead.
      Parameters:
        `path` - is XML path for the stanza element or stanza child for which attribute is retrieved.
        `key` - is an attribute key.
      Returns:
        value of the requested attribute or NULL if the attribute is not set.

    - #### getAttribute

          @Deprecated
          public String getAttribute(String[] path,
                                                 String key)

      Deprecated. use `getAttributeStaticStr(java.lang.String[], java.lang.String)` instead, if possible, if not, contact us so we preserve the API.
      A convenience method for accessing stanza top level or any of it's children attribute. This call is equal to the call:

           packet.getElement().getAttribute(xmlPath, key);

      For performance reasons please consider using `getAttributeStaticStr(java.lang.String[], java.lang.String)` instead.
      Parameters:
        `path` -
        `key` -
      Returns:
        value of the requested attribute or NULL if the attribute is not set.

    - #### getAttribute

          @Deprecated
          public String getAttribute(String path,
                                                 String key)

      Deprecated. use `getAttributeStaticStr(java.lang.String[], java.lang.String)` instead, if possible, or `getAttribute(java.lang.String[], java.lang.String)`
      A convenience method for accessing stanza top level or any of it's children attribute. This call is equal to the call:

           packet.getElement().getAttribute(xmlPath, key);

      Parameters:
        `path` - is XML path for the stanza element or stanza child for which attribute is retrieved.
        `key` - is an attribute key.
      Returns:
        value of the requested attribute or NULL if the attribute is not set.

    - #### getCommand

          public Command getCommand()

      The method always returns NULL. It is overwritten in the `Iq` class where it returns a command identifier if the `iq` stanza represents 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.
      Returns:
        the method always returns a NULL.

    - #### getElemCDataStaticStr

          public String getElemCDataStaticStr(String[] xmlPath)

      Method returns character data from the enclosed stanza for a given stanza element or child pointed by the `xmlPath` parameter. This call is equal to the call:

           packet.getElement().getCData(xmlPath);

      Please note! This method can only be used with static strings or with strings processed through `String.intern()` call. It uses "==" for string comparison for performance reasons. If you pass dynamically built `String[]` to the method call, use `getElemCData(java.lang.String[])` instead.
      Parameters:
        `xmlPath` - is an XML path to the stanza element for which CData is retrieved.
      Returns:
        CData for a given element or NULL if the element does not exist or there is no CData for the element.

    - #### getElemCData

          @Deprecated
          public String getElemCData(String[] xmlPath)

      Deprecated. use `getElemCDataStaticStr(java.lang.String[])` instead, if possible, if not, contact us so we preserve the API.
      Method returns character data from the enclosed stanza for a given stanza element or child pointed by the `xmlPath` parameter. This call is equal to the call:

           packet.getElement().getCData(xmlPath);

      For performance reasons please consider using `getElemCDataStaticStr(java.lang.String[])` instead.
      Parameters:
        `xmlPath` - is an XML path to the stanza element for which CData is retrieved.
      Returns:
        CData for a given element or NULL if the element does not exist or there is no CData for the element.

    - #### getElemCData

          @Deprecated
          public String getElemCData(String xmlPath)

      Deprecated. use `getElemCDataStaticStr(java.lang.String[])` instead, if possible, or `getElemCData(java.lang.String[])`
      Method returns character data from the enclosed stanza for a given stanza element or child pointed by the `xmlPath` parameter. This call is equal to the call:

           packet.getElement().getCData(xmlPath);

      Parameters:
        `xmlPath` - is an XML path to the stanza element for which CData is retrieved.
      Returns:
        CData for a given element or NULL if the element does not exist or there is no CData for the element.

    - #### getElemCData

          public String getElemCData()

      Method return character data for the stanza top element. This call is equal to the call:

           packet.getElement().getCData();

      Returns:
        CData or from the stanza top element or NULL if there is no CData for the element.

    - #### getElemChildrenStaticStr

          public List<Element> getElemChildrenStaticStr(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. This call is equal to the call:

           packet.getElement().getChildrenStaticStr(xmlPath);

      Please note! This method can only be used with static strings or with strings processed through `String.intern()` call. It uses "==" for string comparison for performance reasons. If you pass dynamically built `String[]` to the method call, use `getElemChildren(java.lang.String[])` instead.
      Parameters:
        `xmlPath` - is an XML path to the stanza element for which children are retrieved.
      Returns:
        children list for a given element or NULL if the element does not exist or there is no children for the element.

    - #### getElemChildren

          @Deprecated
          public List<Element> getElemChildren(String[] xmlPath)

      Deprecated. use `getElemChildrenStaticStr(java.lang.String[])` instead, if possible, if not, contact us so we preserve the API.
      Method returns a list of all XML children from the enclosed stanza for a given stanza element or child pointed by the `xmlPath` parameter. This call is equal to the call:

           packet.getElement().getChildren(xmlPath);

      For performance reasons please consider using `getElemChildrenStaticStr(java.lang.String[])` instead.
      Parameters:
        `xmlPath` - is an XML path to the stanza element for which children are retrieved.
      Returns:
        children list for a given element or NULL if the element does not exist or there is no children for the element.

    - #### getElemChildren

          @Deprecated
          public List<Element> getElemChildren(String xmlPath)

      Deprecated. use `getElemChildrenStaticStr(java.lang.String[])` instead, if possible, or `getElemChildren(java.lang.String[])`.
      Method returns a list of all XML children from the enclosed stanza for a given stanza element or child pointed by the `xmlPath` parameter. This call is equal to the call:

           packet.getElement().getChildren(xmlPath);

      Parameters:
        `xmlPath` - is an XML path to the stanza element for which children are retrieved.
      Returns:
        children list for a given element or NULL if the element does not exist or there is no children for the element.

    - #### getElemFrom

          @Deprecated
          public String getElemFrom()

      Deprecated. use getStanzaFrom() instead.
      Method returns a `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.
      Returns:
        a `String` representation of the stanza source address or NULL if the source address has not been set.

    - #### getElemName

          public String getElemName()

      Convenience method for retrieving the stanza top element name. This call is equal to the call:

           packet.getElement().getName();

      Returns:
        the stanza top element name.

    - #### getElemTo

          @Deprecated
          public String getElemTo()

      Deprecated. use getStanzaTo() instead
      Method returns a `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.
      Returns:
        a `String` representation of the stanza destination address or NULL if the destination address has not been set..

    - #### getElement

          public Element getElement()

      Method returns the stanza XML element in DOM format.
      Returns:
        the stanza XML element in DOM format.

    - #### getErrorCondition

          public String getErrorCondition()

      Method parses the stanza and returns the error condition if there is any.
      Returns:
        parsed stanza error condition or NULL if there is not error condition.

    - #### getElNameErrorPath

          protected String[] getElNameErrorPath()

      A convenience method to provide XML path as `String[]` to error element. This method should be override by all classes extending this class.
      Returns:
        XML path to error element.

    - #### getFrom

          public JID getFrom()

      Returns the packet source address. The method works as a following code:

           return (packetFrom != null) ? packetFrom : stanzaFrom;

      Returns:
        a `JID` instance of the packet source address or NULL if neither the packet source address is set nor the stanza source address is set.

    - #### getPacketFrom

          public JID getPacketFrom()

      Returns the packet internal source address.
      Returns:
        a `JID` instance of the packet internal source address or NULL if the packet internal source address has not been set

    - #### getPacketTo

          public JID getPacketTo()

      Returns the packet internal destination address.
      Returns:
        a `JID` instance of the packet internal destination address or NULL if the packet internal destination address has not been set.

    - #### getPermissions

          public Permissions getPermissions()

      Method returns permissions set of the user who has sent the packet. Some packets carry ad-hoc commands which can change server parameters, configuration or can contains other administration commands. Such commands are not executed if the packet sender does not have enough permissions.
      Returns:
        a sender permissions set.

    - #### getPriority

          public Priority getPriority()

      Method returns the packet priority. For more details please refer to `Priority` enumeration.
      Returns:
        the packet priority.

    - #### getProcessorsIds

          public Set<String> getProcessorsIds()

      Method returns a set of all processor IDs which processed the packet. Each session manager processor which handles the packet can mark the packet as processed. This is used internally by the session manager to detect packets which hasn't been processed by any processor, hence a default action is applied to the packet if possible.
      Returns:
        a `Set` of stanza processor IDs which handled the packet.

    - #### getSkippedProcessorsIds

          public Set<String> getSkippedProcessorsIds()

      Method returns a set of all processor IDs which skipped processing packets.
      Returns:
        a `Set` of stanza processor IDs which skipped the packet.

    - #### getStanzaFrom

          public JID getStanzaFrom()

      Method returns source address of the stanza enclosed by this packet.
      Returns:
        a `JID` instance of the stanza source address or NULL if the source address has not been set for the stanza.

    - #### getStanzaId

          public String getStanzaId()

      Method returns the stanza ID if set.
      Returns:
        a `String` representation of the stanza ID or NULL if the ID has not been set for the stanza.

    - #### getStanzaTo

          public JID getStanzaTo()

      Method returns destination address of the stanza enclosed by this packet.
      Returns:
        a `JID` instance of the stanza destination address or NULL if the destination address has not been set for the stanza.

    - #### getTo

          public JID getTo()

      Returns the packet destination address. The method works as a following code:

           return (packetTo != null) ? packetTo : stanzaTo;

      Returns:
        a `JID` instance of the packet destination address or NULL if neither the packet destination address is set nor the stanza destination address is set.

    - #### getType

          public StanzaType getType()

      Method returns the stanza type parsed from the top XML element of the enclosed stanza.
      Returns:
        a `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.

    - #### getXMLNS

          public String getXMLNS()

      Returns the enclosed stanza top element XMLNS. This call is equal to the call:

           packet.getElement().getXMLNS();

      Returns:
        a `String` instance of the stanza top element XMLNS.

    - #### initVars

          public void initVars(JID stanzaFrom,
                               JID stanzaTo)

      The method allows for re-syncing stanza JIDs stored in the packet with the attributes of the stanza if they have been changed for any reason. Method mostly used internally only. Normally stanza carried by this Packet instance must not be changed, however there are rare occasions when it has to be changed. RFC requires that the server adds missing 'from' attribute to every packet sent by the user. It would be highly inefficient to create a new instance of the data just to add the missing from address. In such a case SM adds missing attribute but then stanza preparsed JIDs stored in the packet are out of sync with the enclosed stanza. This method allows for setting correct stanza JIDs for the packet fields without a need to reparse the stanza.
      Parameters:
        `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.

    - #### initVars

          public void initVars()
                        throws TigaseStringprepException

      The method allows for re-syncing/parsing stanza JIDs stored in the packet with the attributes of the stanza if they have been changed for any reason. Method mostly used internally only. Normally stanza carried by this Packet instance must not be changed, however there are rare occasions when it is needed. RFC requires that the server adds missing 'from' attribute to every packet sent by the user. It would be highly inefficient to create a new instance of the data just to add the missing from address. In such a case SM adds missing attribute but then stanza pre-parsed JIDs stored in the packet are out of sync with the enclosed stanza. This method causes stanza JIDs re-parsing and setting the packet variables.
      Throws:
        `TigaseStringprepException` - if the stringprep error occurs during the stanza JIDs parsing.

    - #### isCommand

          public boolean isCommand()

      The method checks whether the stanza enclosed by this `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.
      Returns:
        a `boolean` value `true` if the stanza is an ad-hoc command and `false` otherwise.

    - #### isElement

          public boolean isElement(String name,
                                   String xmlns)

      The method checks whether the enclosed stanza is a specific XML element. That is, it checks whether the stanza element name and XMLNS is exactly the same as given parameters. This is a convenience method which logic is equal to the code below: `return packet.getElement().getName() == name && packet.getElement().getXMLNS() == xmlns;`
      Parameters:
        `name` - is a `String` representing the XML element name.
        `xmlns` - is a `String` representing the XML xmlns value.
      Returns:
        `true` if stanza element name and XMLNS is exactly the same as given parameters, `false` otherwise.

    - #### isRouted

          public boolean isRouted()

      Method determines whether the stanza represents so called routed packet. A routed packet is a packet created by a component responsible for Communication with external components. In certain work mode it can send over the link the whole packet information with all internal states and addresses. Such a packet also encloses original stanza with all it's attributes.
      Returns:
        a `boolean` value of `true` if the packet is routed and `false` otherwise.

    - #### isServiceDisco

          public boolean isServiceDisco()

      A convenience method which checks whether the enclosed stanza is a service discovery query. 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.
      Returns:
        a `boolean` value `true` if the stanza is a a service discovery query and `false` otherwise.

    - #### isXMLNSStaticStr

          public boolean isXMLNSStaticStr(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. The `elementPath` is directory path like string. Please note! This method can only be used with static strings or with strings processed through `String.intern()` call. It uses "==" for string comparison for performance reasons. If you pass dynamically built `String[]` to the method call, use `isXMLNS(java.lang.String[], java.lang.String)` instead.
      Parameters:
        `elementPath` - is a `String[]` value which represents XML element path to a desired child element.
        `xmlns` - is a `String` value which represents XML XMLNS.
      Returns:
        a `true` is element given in parameters is found in the packet stanza, otherwise `false`

    - #### isXMLNS

          @Deprecated
          public boolean isXMLNS(String[] elementPath,
                                             String xmlns)

      Deprecated. use `isXMLNSStaticStr(String[], String)` instead, if possible, if not contact us so we preserve the API.
      The method checks whether the enclosed stanza contains an XML element and XML child element for a given element path and xmlns. The `elementPath` is a String array with path elements. For performance reasons please consider using `isXMLNSStaticStr(java.lang.String[], java.lang.String)` instead.
      Parameters:
        `elementPath` - is a `String[]` value which represents XML element path to a desired child element.
        `xmlns` - is a `String` value which represents XML XMLNS.
      Returns:
        a `true` is element given in parameters is found in the packet stanza, otherwise `false`

    - #### isXMLNS

          @Deprecated
          public boolean isXMLNS(String elementPath,
                                             String xmlns)

      Deprecated. use `isXMLNSStaticStr(String[], String)` instead, if possible, or `isXMLNS(String[], String)`
      Checks whether the XML stanza contains XML element with given XML path and element name and XMLNS. This is inefficient method and highly recommended not to use. Please use the other methods which accept `String[]` instead.
      Parameters:
        `elementPath` - is a string with XML path in form of: "/root/child1/child2"
        `xmlns` - is a valid XML namespace.
      Returns:
        a `true` is element given in parameters is found in the packet stanza, otherwise `false`

    - #### notProcessedBy

          public void notProcessedBy(String id)

      The method marks that the packet has NOT been processed by a packet processor with a given ID.
      Parameters:
        `id` - is a `String` instance of the packet processer identifier.

    - #### setXMLNS

          public void setXMLNS(String xmlns)

      Method allows to set-force XMLNS for the element. This is mostly used in cases where there is no XMLNS provided for the element (by the client for example) and then a default one is used. However, in some contexts a default XMLNS might be confusing such as when the packet is passed between s2s to c2s connection and the default XMLNS changes.
      Parameters:
        `xmlns` - a valid XMLNS string for the element.

    - #### okResult

          public 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. 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.
      Parameters:
        `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.
      Returns:
        a new `Packet` instance with an OK (result) type stanza which is a response to this `Packet` instance.

    - #### okResult

          public Packet okResult(Element includeXML,
                                 int originalXML)

      Method returns a modified copy of the `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.
      Parameters:
        `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.
      Returns:
        a new `Packet` instance with an OK (result) type stanza which is a response to this `Packet` instance.

    - #### packRouted

          public 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.
      Returns:
        a new `Packet` instance with `route` stanza.

    - #### processedBy

          public void processedBy(String id)

      The method marks that the packet has been processed by a packet processor with a given ID.
      Parameters:
        `id` - is a `String` instance of the packet processer identifier.

    - #### setPacketFrom

          public void setPacketFrom(JID from)

      The method sets a source address for the `Packet` instance.
      Parameters:
        `from` - is a `JID` instance of the packet new source address.

    - #### setPacketTo

          public void setPacketTo(JID to)

      The method sets a destination address for the `Packet` instance.
      Parameters:
        `to` - is a `JID` instance of the packet new destination address.

    - #### setPermissions

          public void setPermissions(Permissions perm)

      The method sets permissions for the packet of a user who sent the stanza.
      Parameters:
        `perm` - is `Permissions` instance of the stanza sender permissions calculated by the session manager.

    - #### setPriority

          public void setPriority(Priority priority)

      The method sets the packet priority. Depending on the priority the packet is put to a queue with corresponding priority. This matter only on system which experience overload and some packets may be delivered with a delay if they are low priority packets.
      Parameters:
        `priority` - is a new `Priority` instance set for the packet.

    - #### swapElemFromTo

          @Deprecated
          public Packet swapElemFromTo()

      Deprecated. Use `swapStanzaFromTo()` instead.
      The method left for compatibility with an old API reasons. Use `swapStanzaFromTo()` instead.
      Returns:
        a new packet instance with a copy of the stanza element with swapped source and destination addresses.

    - #### swapElemFromTo

          @Deprecated
          public Packet swapElemFromTo(StanzaType type)

      Deprecated. Use `swapStanzaFromTo()` instead.
      The method left for compatibility with an old API reasons. Use `swapStanzaFromTo()` instead.
      Parameters:
        `type` - a new stanza type which has to be set to the generated stanza copy.
      Returns:
        a new packet instance with a copy of the stanza element with swapped source and destination addresses.

    - #### swapFromTo

          public Packet swapFromTo(Element el,
                                   JID stanzaFrom,
                                   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. 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.
      Parameters:
        `el` - is an XML element set for the new packet.
        `stanzaFrom` - is the stanza source address
        `stanzaTo` - is the stanza destination address
      Returns:
        a new `Packet` instance.

    - #### swapFromTo

          public Packet swapFromTo()

      Creates a new `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.
      Returns:
        a new `Packet` instance.

    - #### swapStanzaFromTo

          public Packet swapStanzaFromTo()

      The method creates a new `Packet` instance with a stanza copy with swapped source and destination addresses. The packet source and destination addresses are set to null.
      Returns:
        a new `Packet` instance.

    - #### swapStanzaFromTo

          public 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. The packet source and destination addresses are set to null.
      Parameters:
        `type` - is a new type for the stanza copy to set.
      Returns:
        a new `Packet` instance.

    - #### toStringFull

          public String toStringFull()

      The method converts the `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).
      Returns:
        a `String` representation of the packet instance.

    - #### toString

          public String toString()

      Provides human-readable string presentation of the `Packet` object. It is not a XMPP stanza only, it also contains some Tigase specific meta-data.
      Overrides:
        `toString` in class `Object`
      Returns:
        human-readable string presentation of the `Packet` object.

    - #### toString

          public String toString(boolean secure)

      Is a convenience method which allows you to call always the same method but change (configure) whether you want to get a secure packet string representation or full representation.
      Parameters:
        `secure` - parameter specifies whether the secure packet representation should be returned (`true` value) or the full one (`false`).
      Returns:
        a `String` representation of the packet instance.

    - #### toStringSecure

          public String toStringSecure()

      The method returns a `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.
      Returns:
        a `String` representation of the packet instance.

    - #### unpackRouted

          public Packet unpackRouted()
                              throws TigaseStringprepException

      The method unpacks the original packet and stanza from `route` stanza. This is the opposite action to the `packRouted()` method.
      Returns:
        a new instance of the `Packet` class with unpacket packet and stanza from `route` stanza.
      Throws:
        `TigaseStringprepException` - if there was a problem with addresses stringprep processing.

    - #### wasProcessed

          public boolean wasProcessed()

      The method determines whether the packet has been processed by any of the packet processors. In fact it says whether there has been called method `processedBy(...)` on the packet.
      Returns:
        a `boolean` value of `true` of the packet was processed by any processor and `false` otherwise.

    - #### wasSkipped

          public boolean wasSkipped()

      The method determines whether the packet was directed to processing by any packet processor, but it wasn't processed by them because of internal queue full.
      Returns:
        `true` if packet was skipped by any processor.

    - #### wasProcessedBy

          public boolean wasProcessedBy(String id)

      The method checks whether the packet has been processed by a packet processor with the specified ID.
      Parameters:
        `id` - is a `String` instance of the packet processor identifier.
      Returns:
        a `boolean` value of `true` of the packet was processed by a processor with specified ID and `false` otherwise.

Copyright © 2022 "Tigase, Inc.". All rights reserved.