001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  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.apache.commons.net;
019
020import java.util.EventObject;
021
022/**
023 * There exists a large class of IETF protocols that work by sending an ASCII text command and arguments to a server, and then receiving an ASCII text reply.
024 * For debugging and other purposes, it is extremely useful to log or keep track of the contents of the protocol messages. The ProtocolCommandEvent class
025 * coupled with the {@link org.apache.commons.net.ProtocolCommandListener} interface facilitate this process.
026 *
027 *
028 * @see ProtocolCommandListener
029 * @see ProtocolCommandSupport
030 */
031
032public class ProtocolCommandEvent extends EventObject {
033    private static final long serialVersionUID = 403743538418947240L;
034
035    private final int replyCode;
036    private final boolean isCommand;
037    private final String message, command;
038
039    /**
040     * Creates a ProtocolCommandEvent signalling a reply to a command was received. ProtocolCommandEvents created with this constructor should only be sent
041     * after a complete command reply has been received from a server.
042     *
043     * @param source    The source of the event.
044     * @param replyCode The integer code indicating the natureof the reply. This will be the protocol integer value for protocols that use integer reply codes,
045     *                  or the reply class constant corresponding to the reply for protocols like POP3 that use strings like OK rather than integer codes (i.e.,
046     *                  POP3Repy.OK).
047     * @param message   The entire reply as received from the server.
048     */
049    public ProtocolCommandEvent(final Object source, final int replyCode, final String message) {
050        super(source);
051        this.replyCode = replyCode;
052        this.message = message;
053        this.isCommand = false;
054        this.command = null;
055    }
056
057    /**
058     * Creates a ProtocolCommandEvent signalling a command was sent to the server. ProtocolCommandEvents created with this constructor should only be sent after
059     * a command has been sent, but before the reply has been received.
060     *
061     * @param source  The source of the event.
062     * @param command The string representation of the command type sent, not including the arguments (e.g., "STAT" or "GET").
063     * @param message The entire command string verbatim as sent to the server, including all arguments.
064     */
065    public ProtocolCommandEvent(final Object source, final String command, final String message) {
066        super(source);
067        this.replyCode = 0;
068        this.message = message;
069        this.isCommand = true;
070        this.command = command;
071    }
072
073    /**
074     * Returns the string representation of the command type sent (e.g., "STAT" or "GET"). If the ProtocolCommandEvent is a reply event, then null is returned.
075     *
076     * @return The string representation of the command type sent, or null if this is a reply event.
077     */
078    public String getCommand() {
079        return command;
080    }
081
082    /**
083     * Returns the entire message sent to or received from the server. Includes the line terminator.
084     *
085     * @return The entire message sent to or received from the server.
086     */
087    public String getMessage() {
088        return message;
089    }
090
091    /**
092     * Returns the reply code of the received server reply. Undefined if this is not a reply event.
093     *
094     * @return The reply code of the received server reply. Undefined if not a reply event.
095     */
096    public int getReplyCode() {
097        return replyCode;
098    }
099
100    /**
101     * Returns true if the ProtocolCommandEvent was generated as a result of sending a command.
102     *
103     * @return true If the ProtocolCommandEvent was generated as a result of sending a command. False otherwise.
104     */
105    public boolean isCommand() {
106        return isCommand;
107    }
108
109    /**
110     * Returns true if the ProtocolCommandEvent was generated as a result of receiving a reply.
111     *
112     * @return true If the ProtocolCommandEvent was generated as a result of receiving a reply. False otherwise.
113     */
114    public boolean isReply() {
115        return !isCommand();
116    }
117}