001/**
002 *
003 * Copyright 2003-2007 Jive Software, 2017 Florian Schmaus.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smack.debugger;
019
020import java.io.Reader;
021import java.io.Writer;
022
023import org.jivesoftware.smack.XMPPConnection;
024import org.jivesoftware.smack.packet.TopLevelStreamElement;
025
026import org.jxmpp.jid.EntityFullJid;
027
028/**
029 * Interface that allows for implementing classes to debug XML traffic. That is a GUI window that
030 * displays XML traffic.<p>
031 *
032 * Every implementation of this interface <b>must</b> have a public constructor with the following
033 * arguments: XMPPConnection, Writer, Reader.
034 *
035 * @author Gaston Dombiak
036 */
037public abstract class SmackDebugger {
038
039    protected final XMPPConnection connection;
040
041    protected SmackDebugger(XMPPConnection connection) {
042        this.connection = connection;
043    }
044
045    /**
046     * Called when a user has logged in to the server. The user could be an anonymous user, this
047     * means that the user would be of the form host/resource instead of the form
048     * user@host/resource.
049     *
050     * @param user the user@host/resource that has just logged in
051     */
052    // TODO: Should be replaced with a connection listener authenticed().
053    public abstract void userHasLogged(EntityFullJid user);
054
055    /**
056     * Returns a new special Reader that wraps the new connection Reader. The connection
057     * has been secured so the connection is using a new reader and writer. The debugger
058     * needs to wrap the new reader and writer to keep being notified of the connection
059     * traffic.
060     *
061     * @param reader connection reader.
062     * @return a new special Reader that wraps the new connection Reader.
063     */
064    public abstract Reader newConnectionReader(Reader reader);
065
066    /**
067     * Returns a new special Writer that wraps the new connection Writer. The connection
068     * has been secured so the connection is using a new reader and writer. The debugger
069     * needs to wrap the new reader and writer to keep being notified of the connection
070     * traffic.
071     *
072     * @param writer connection writer.
073     * @return a new special Writer that wraps the new connection Writer.
074     */
075    public abstract Writer newConnectionWriter(Writer writer);
076
077    /**
078     * Used by the connection to notify about an incoming top level stream element.
079     * <p>
080     * This method is invoked right after the incoming stream was parsed.
081     * </p>
082     *
083     * @param streamElement the incoming top level stream element.
084     */
085    public abstract void onIncomingStreamElement(TopLevelStreamElement streamElement);
086
087    /**
088     * Used by the connection to notify about a outgoing top level stream element.
089     * <p>
090     * This method is invoked right before the element is serialized to XML and put into the outgoing stream.
091     * </p>
092     *
093     * @param streamElement the outgoing top level stream element.
094     */
095    public abstract void onOutgoingStreamElement(TopLevelStreamElement streamElement);
096
097}