1/**
2 * $RCSfile$
3 * $Revision$
4 * $Date$
5 *
6 * Copyright 2003-2007 Jive Software.
7 *
8 * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
9 * you may not use this file except in compliance with the License.
10 * You may obtain a copy of the License at
11 *
12 *     http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS,
16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 * See the License for the specific language governing permissions and
18 * limitations under the License.
19 */
20
21package org.jivesoftware.smack.debugger;
22
23import java.io.*;
24
25import org.jivesoftware.smack.*;
26
27/**
28 * Interface that allows for implementing classes to debug XML traffic. That is a GUI window that
29 * displays XML traffic.<p>
30 *
31 * Every implementation of this interface <b>must</b> have a public constructor with the following
32 * arguments: Connection, Writer, Reader.
33 *
34 * @author Gaston Dombiak
35 */
36public interface SmackDebugger {
37
38    /**
39     * Called when a user has logged in to the server. The user could be an anonymous user, this
40     * means that the user would be of the form host/resource instead of the form
41     * user@host/resource.
42     *
43     * @param user the user@host/resource that has just logged in
44     */
45    public abstract void userHasLogged(String user);
46
47    /**
48     * Returns the special Reader that wraps the main Reader and logs data to the GUI.
49     *
50     * @return the special Reader that wraps the main Reader and logs data to the GUI.
51     */
52    public abstract Reader getReader();
53
54    /**
55     * Returns the special Writer that wraps the main Writer and logs data to the GUI.
56     *
57     * @return the special Writer that wraps the main Writer and logs data to the GUI.
58     */
59    public abstract Writer getWriter();
60
61    /**
62     * Returns a new special Reader that wraps the new connection Reader. The connection
63     * has been secured so the connection is using a new reader and writer. The debugger
64     * needs to wrap the new reader and writer to keep being notified of the connection
65     * traffic.
66     *
67     * @return a new special Reader that wraps the new connection Reader.
68     */
69    public abstract Reader newConnectionReader(Reader reader);
70
71    /**
72     * Returns a new special Writer that wraps the new connection Writer. The connection
73     * has been secured so the connection is using a new reader and writer. The debugger
74     * needs to wrap the new reader and writer to keep being notified of the connection
75     * traffic.
76     *
77     * @return a new special Writer that wraps the new connection Writer.
78     */
79    public abstract Writer newConnectionWriter(Writer writer);
80
81    /**
82     * Returns the thread that will listen for all incoming packets and write them to the GUI.
83     * This is what we call "interpreted" packet data, since it's the packet data as Smack sees
84     * it and not as it's coming in as raw XML.
85     *
86     * @return the PacketListener that will listen for all incoming packets and write them to
87     * the GUI
88     */
89    public abstract PacketListener getReaderListener();
90
91    /**
92     * Returns the thread that will listen for all outgoing packets and write them to the GUI.
93     *
94     * @return the PacketListener that will listen for all sent packets and write them to
95     * the GUI
96     */
97    public abstract PacketListener getWriterListener();
98}