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;
019import java.util.EventObject;
020
021/**
022 * There exists a large class of IETF protocols that work by sending an
023 * ASCII text command and arguments to a server, and then receiving an
024 * ASCII text reply.  For debugging and other purposes, it is extremely
025 * useful to log or keep track of the contents of the protocol messages.
026 * The ProtocolCommandEvent class coupled with the
027 * {@link org.apache.commons.net.ProtocolCommandListener}
028 *  interface facilitate this process.
029 *
030 *
031 * @see ProtocolCommandListener
032 * @see ProtocolCommandSupport
033 */
034
035public class ProtocolCommandEvent extends EventObject
036{
037    private static final long serialVersionUID = 403743538418947240L;
038
039    private final int replyCode;
040    private final boolean isCommand;
041    private final String message, command;
042
043    /**
044     * Creates a ProtocolCommandEvent signalling a command was sent to
045     * the server.  ProtocolCommandEvents created with this constructor
046     * should only be sent after a command has been sent, but before the
047     * reply has been received.
048     *
049     * @param source  The source of the event.
050     * @param command The string representation of the command type sent, not
051     *      including the arguments (e.g., "STAT" or "GET").
052     * @param message The entire command string verbatim as sent to the server,
053     *        including all arguments.
054     */
055    public ProtocolCommandEvent(final Object source, final String command, final String message)
056    {
057        super(source);
058        this.replyCode = 0;
059        this.message = message;
060        this.isCommand = true;
061        this.command = command;
062    }
063
064
065    /**
066     * Creates a ProtocolCommandEvent signalling a reply to a command was
067     * received.  ProtocolCommandEvents created with this constructor
068     * should only be sent after a complete command reply has been received
069     * fromt a server.
070     *
071     * @param source  The source of the event.
072     * @param replyCode The integer code indicating the natureof the reply.
073     *   This will be the protocol integer value for protocols
074     *   that use integer reply codes, or the reply class constant
075     *   corresponding to the reply for protocols like POP3 that use
076     *   strings like OK rather than integer codes (i.e., POP3Repy.OK).
077     * @param message The entire reply as received from the server.
078     */
079    public ProtocolCommandEvent(final Object source, final int replyCode, final String message)
080    {
081        super(source);
082        this.replyCode = replyCode;
083        this.message = message;
084        this.isCommand = false;
085        this.command = null;
086    }
087
088    /**
089     * Returns the string representation of the command type sent (e.g., "STAT"
090     * or "GET").  If the ProtocolCommandEvent is a reply event, then null
091     * is returned.
092     *
093     * @return The string representation of the command type sent, or null
094     *         if this is a reply event.
095     */
096    public String getCommand()
097    {
098        return command;
099    }
100
101
102    /**
103     * Returns the reply code of the received server reply.  Undefined if
104     * this is not a reply event.
105     *
106     * @return The reply code of the received server reply.  Undefined if
107     *         not a reply event.
108     */
109    public int getReplyCode()
110    {
111        return replyCode;
112    }
113
114    /**
115     * Returns true if the ProtocolCommandEvent was generated as a result
116     * of sending a command.
117     *
118     * @return true If the ProtocolCommandEvent was generated as a result
119     * of sending a command.  False otherwise.
120     */
121    public boolean isCommand()
122    {
123        return isCommand;
124    }
125
126    /**
127     * Returns true if the ProtocolCommandEvent was generated as a result
128     * of receiving a reply.
129     *
130     * @return true If the ProtocolCommandEvent was generated as a result
131     * of receiving a reply.  False otherwise.
132     */
133    public boolean isReply()
134    {
135        return !isCommand();
136    }
137
138    /**
139     * Returns the entire message sent to or received from the server.
140     * Includes the line terminator.
141     *
142     * @return The entire message sent to or received from the server.
143     */
144    public String getMessage()
145    {
146        return message;
147    }
148}