1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
/**
* $RCSfile$
* $Revision$
* $Date$
*
* Copyright (C) 2004 Jive Software. All rights reserved.
*
* This software is published under the terms of the GNU Public License (GPL),
* a copy of which is included in this distribution.
*/
package org.jivesoftware.messenger;
import java.util.Iterator;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;
/**
* <p>Represents an XML fragment with particular meaning in XMPP.</p>
* <p>XMPP systems will be dealing with many XML fragments and this class
* allows the system to generically handle fragments without particular knowledge
* of what they contain (and hiding optimizations in representing, storing,
* and sending these fragments). The most common fragments the system deals
* with are XMPP packets of the three cardinal types: Message, Presence,
* and IQ. However, these packets can contain protocol specific, or custom
* meta-data represented by additional fragments.</p>
* <p>Fragments allows parsers to breakdown XMPP packets into fragment object
* models. A higher abstraction level than XML DOM's that must create a node
* for every XML element. However, they also may be implemented as simple
* wrappers around raw XML DOM's if necessary.</p>
*
* @author Iain Shigeoka
*/
public interface XMPPFragment {
/**
* <p>Returns a namespace associated with this meta-data or null if none has been associated.</p>
*
* @return the namespace associated with this meta-data.
*/
public String getNamespace();
/**
* <p>Sets a namespace associated with this meta-data or null if none has been associated.</p>
*
* @param namespace the namespace associated with this meta-data.
*/
public void setNamespace(String namespace);
/**
* <p>Returns a name associated with this meta-data or null if none has been associated.</p>
*
* @return the name associated with this meta-data.
*/
public String getName();
/**
* Sets a namespace associated with this meta-data or null if none has been associated.
*
* @param name The namespace associated with this meta-data
*/
public void setName(String name);
/**
* <p>Sends the fragment as a string to the given writer.</p>
* <p>A fragment will always be written as a completely self
* contained, well-formed XML fragment.</p>
*
* @param xmlSerializer The serializer to send the jabber packet
* @param version The XMPP version for the stream (0 is old Jabber, 1 is XMPP 1.0)
* @throws XMLStreamException If there is a problem with the connection
*/
void send(XMLStreamWriter xmlSerializer, int version) throws XMLStreamException;
/**
* <p>Generates an independent, deep copy of this packet.</p>
*
* @return The deep copy of the packet
*/
XMPPFragment createDeepCopy();
/**
* <p>Adds another fragment as a child fragment of this one.</p>
* <p>Child fragments can be used to build a DOM like tree of fragments. However,
* the typical use case in Messenger packets is to store meta-data as child fragments
* and standard data as member fields accessed via standard setter/getters.</p>
*
* @param fragment the fragment to add to this packet.
*/
void addFragment(XMPPFragment fragment);
/**
* <p>Obtain an iterator of child fragments.</p>
*
* @return An iterator over all child fragments.
*/
Iterator getFragments();
/**
* Returns the fragment whose name and namespace matches the requested ones or <tt>null</tt> if
* none. It is assumed that there is at most one fragment per name and namespace.
*
* @param name the name of the fragment to search.
* @param namespace the namespace of the fragment to search.
* @return the fragment whose name and namespace matches the requested ones or <tt>null</tt> if
* none.
*/
XMPPFragment getFragment(String name, String namespace);
/**
* Remove any child fragments from this fragment.
*/
void clearFragments();
/**
* <p>Make a best guess estimate on size in bytes of an XML string representation of
* this fragment.</p>
* <p>There are several server operations that can be helped by hints on fragment sizes
* such as offline storage, auditing, caching, etc. To this end, this method provides
* a guess where speed of calculation and lowest resource impact are highest priorities
* (you should not generate the XML string and count the bytes).</p>
*
* @return an estimate in bytes of the size of this fragment as an XML string
* (assume UTF-8 encoding)
*/
int getSize();
}