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 *      https://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    /**
036     * The integer code indicating the natureof the reply. This will be the protocol integer value for protocols that use integer reply codes, or the reply
037     * class constant corresponding to the reply for protocols like POP3 that use strings like OK rather than integer codes (i.e., POP3Repy.OK).
038     */
039    private final int replyCode;
040
041    /**
042     * Whether the ProtocolCommandEvent was generated as a result of sending a command.
043     */
044    private final boolean isCommand;
045
046    /**
047     * The entire reply as received from the server.
048     */
049    private final String message;
050
051    /**
052     * The string representation of the command type sent, not including the arguments (e.g., "STAT" or "GET").
053     */
054    private final String command;
055
056    /**
057     * Creates a ProtocolCommandEvent signaling a reply to a command was received. ProtocolCommandEvents created with this constructor should only be sent
058     * after a complete command reply has been received from a server.
059     *
060     * @param source    The source of the event.
061     * @param replyCode The integer code indicating the natureof the reply. This will be the protocol integer value for protocols that use integer reply codes,
062     *                  or the reply class constant corresponding to the reply for protocols like POP3 that use strings like OK rather than integer codes (i.e.,
063     *                  POP3Repy.OK).
064     * @param message   The entire reply as received from the server.
065     */
066    public ProtocolCommandEvent(final Object source, final int replyCode, final String message) {
067        super(source);
068        this.replyCode = replyCode;
069        this.message = message;
070        this.isCommand = false;
071        this.command = null;
072    }
073
074    /**
075     * Creates a ProtocolCommandEvent signaling a command was sent to the server. ProtocolCommandEvents created with this constructor should only be sent after
076     * a command has been sent, but before the reply has been received.
077     *
078     * @param source  The source of the event.
079     * @param command The string representation of the command type sent, not including the arguments (e.g., "STAT" or "GET").
080     * @param message The entire command string verbatim as sent to the server, including all arguments.
081     */
082    public ProtocolCommandEvent(final Object source, final String command, final String message) {
083        super(source);
084        this.replyCode = 0;
085        this.message = message;
086        this.isCommand = true;
087        this.command = command;
088    }
089
090    /**
091     * Gets the string representation of the command type sent (e.g., "STAT" or "GET"). If the ProtocolCommandEvent is a reply event, then null is returned.
092     *
093     * @return The string representation of the command type sent, or null if this is a reply event.
094     */
095    public String getCommand() {
096        return command;
097    }
098
099    /**
100     * Gets the entire message sent to or received from the server. Includes the line terminator.
101     *
102     * @return The entire message sent to or received from the server.
103     */
104    public String getMessage() {
105        return message;
106    }
107
108    /**
109     * Gets the reply code of the received server reply. Undefined if this is not a reply event.
110     *
111     * @return The reply code of the received server reply. Undefined if not a reply event.
112     */
113    public int getReplyCode() {
114        return replyCode;
115    }
116
117    /**
118     * Tests whether the ProtocolCommandEvent was generated as a result of sending a command.
119     *
120     * @return true If the ProtocolCommandEvent was generated as a result of sending a command. False otherwise.
121     */
122    public boolean isCommand() {
123        return isCommand;
124    }
125
126    /**
127     * Tests whether the ProtocolCommandEvent was generated as a result of receiving a reply.
128     *
129     * @return true If the ProtocolCommandEvent was generated as a result of receiving a reply. False otherwise.
130     */
131    public boolean isReply() {
132        return !isCommand();
133    }
134}