View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.net.tftp;
19  
20  import java.net.DatagramPacket;
21  import java.net.InetAddress;
22  
23  /**
24   * TFTPPacket is an abstract class encapsulating the functionality common to the 5 types of TFTP packets. It also provides a static factory method that will
25   * create the correct TFTP packet instance from a datagram. This relieves the programmer from having to figure out what kind of TFTP packet is contained in a
26   * datagram and create it himself.
27   * <p>
28   * Details regarding the TFTP protocol and the format of TFTP packets can be found in RFC 783. But the point of these classes is to keep you from having to
29   * worry about the internals. Additionally, only very few people should have to care about any of the TFTPPacket classes or derived classes. Almost all users
30   * should only be concerned with the {@link org.apache.commons.net.tftp.TFTPClient} class {@link org.apache.commons.net.tftp.TFTPClient#receiveFile
31   * receiveFile()} and {@link org.apache.commons.net.tftp.TFTPClient#sendFile sendFile()} methods.
32   * </p>
33   *
34   * @see TFTPPacketException
35   * @see TFTP
36   */
37  
38  public abstract class TFTPPacket {
39      /**
40       * The minimum size of a packet. This is 4 bytes. It is enough to store the opcode and blocknumber or other required data depending on the packet type.
41       */
42      static final int MIN_PACKET_SIZE = 4;
43  
44      /**
45       * This is the actual TFTP spec identifier and is equal to 1. Identifier returned by {@link #getType getType()} indicating a read request packet.
46       */
47      public static final int READ_REQUEST = 1;
48  
49      /**
50       * This is the actual TFTP spec identifier and is equal to 2. Identifier returned by {@link #getType getType()} indicating a write request packet.
51       */
52      public static final int WRITE_REQUEST = 2;
53  
54      /**
55       * This is the actual TFTP spec identifier and is equal to 3. Identifier returned by {@link #getType getType()} indicating a data packet.
56       */
57      public static final int DATA = 3;
58  
59      /**
60       * This is the actual TFTP spec identifier and is equal to 4. Identifier returned by {@link #getType getType()} indicating an acknowledgement packet.
61       */
62      public static final int ACKNOWLEDGEMENT = 4;
63  
64      /**
65       * This is the actual TFTP spec identifier and is equal to 5. Identifier returned by {@link #getType getType()} indicating an error packet.
66       */
67      public static final int ERROR = 5;
68  
69      /**
70       * TFTP spec identifier {@value}. Identifier returned by {@link #getType getType()} indicating an options acknowledgement packet.
71       *
72       * @since 3.12.0
73       */
74      public static final int OACK = 6;
75  
76      /**
77       * The TFTP data packet maximum segment size in bytes. This is 512 and is useful for those familiar with the TFTP protocol who want to use the
78       * {@link org.apache.commons.net.tftp.TFTP} class methods to implement their own TFTP servers or clients.
79       */
80      public static final int SEGMENT_SIZE = 512;
81  
82      /**
83       * When you receive a datagram that you expect to be a TFTP packet, you use this factory method to create the proper TFTPPacket object encapsulating the
84       * data contained in that datagram. This method is the only way you can instantiate a TFTPPacket derived class from a datagram.
85       *
86       * @param datagram The datagram containing a TFTP packet.
87       * @return The TFTPPacket object corresponding to the datagram.
88       * @throws TFTPPacketException If the datagram does not contain a valid TFTP packet.
89       */
90      public static final TFTPPacket newTFTPPacket(final DatagramPacket datagram) throws TFTPPacketException {
91          if (datagram.getLength() < MIN_PACKET_SIZE) {
92              throw new TFTPPacketException("Bad packet. Datagram data length is too short.");
93          }
94          final byte[] data = datagram.getData();
95          final TFTPPacket packet;
96          switch (data[1]) {
97          case READ_REQUEST:
98              packet = new TFTPReadRequestPacket(datagram);
99              break;
100         case WRITE_REQUEST:
101             packet = new TFTPWriteRequestPacket(datagram);
102             break;
103         case DATA:
104             packet = new TFTPDataPacket(datagram);
105             break;
106         case ACKNOWLEDGEMENT:
107             packet = new TFTPAckPacket(datagram);
108             break;
109         case ERROR:
110             packet = new TFTPErrorPacket(datagram);
111             break;
112         default:
113             throw new TFTPPacketException("Bad packet.  Invalid TFTP operator code.");
114         }
115         return packet;
116     }
117 
118     /** The type of packet. */
119     int type;
120 
121     /** The port the packet came from or is going to. */
122     int port;
123 
124     /** The host the packet is going to be sent or where it came from. */
125     InetAddress address;
126 
127     /**
128      * This constructor is not visible outside the package. It is used by subclasses within the package to initialize base data.
129      *
130      * @param type    The type of the packet.
131      * @param address The host the packet came from or is going to be sent.
132      * @param port    The port the packet came from or is going to be sent.
133      **/
134     TFTPPacket(final int type, final InetAddress address, final int port) {
135         this.type = type;
136         this.address = address;
137         this.port = port;
138     }
139 
140     /**
141      * Gets the address of the host where the packet is going to be sent or where it came from.
142      *
143      * @return The type of the packet.
144      */
145     public final InetAddress getAddress() {
146         return address;
147     }
148 
149     /**
150      * Gets the port where the packet is going to be sent or where it came from.
151      *
152      * @return The port where the packet came from or where it is going.
153      */
154     public final int getPort() {
155         return port;
156     }
157 
158     /**
159      * Gets the type of the packet.
160      *
161      * @return The type of the packet.
162      */
163     public final int getType() {
164         return type;
165     }
166 
167     /**
168      * Creates a UDP datagram containing all the TFTP packet data in the proper format. This is an abstract method, exposed to the programmer in case he wants
169      * to implement his own TFTP client instead of using the {@link org.apache.commons.net.tftp.TFTPClient} class. Under normal circumstances, you should not
170      * have a need to call this method.
171      *
172      * @return A UDP datagram containing the TFTP packet.
173      */
174     public abstract DatagramPacket newDatagram();
175 
176     /**
177      * This is an abstract method only available within the package for implementing efficient datagram transport by eliminating buffering. It takes a datagram
178      * as an argument, and a byte buffer in which to store the raw datagram data. Inside the method, the data should be set as the datagram's data and the
179      * datagram returned.
180      *
181      * @param datagram The datagram to create.
182      * @param data     The buffer to store the packet and to use in the datagram.
183      * @return The datagram argument.
184      */
185     abstract DatagramPacket newDatagram(DatagramPacket datagram, byte[] data);
186 
187     /**
188      * Sets the host address where the packet is going to be sent.
189      *
190      * @param address the address to set
191      */
192     public final void setAddress(final InetAddress address) {
193         this.address = address;
194     }
195 
196     /**
197      * Sets the port where the packet is going to be sent.
198      *
199      * @param port the port to set
200      */
201     public final void setPort(final int port) {
202         this.port = port;
203     }
204 
205     /**
206      * For debugging
207      *
208      * @since 3.6
209      */
210     @Override
211     public String toString() {
212         return address + " " + port + " " + type;
213     }
214 }