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    *      http://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.ftp;
19  import java.io.Serializable;
20  import java.util.Calendar;
21  
22  /***
23   * The FTPFile class is used to represent information about files stored
24   * on an FTP server.  Because there is no standard representation for
25   * file information on FTP servers, it may not always be possible to
26   * extract all the information that can be represented by FTPFile, or
27   * it may even be possible to extract more information.  In cases where
28   * more information can be extracted, you will want to subclass FTPFile
29   * and implement your own {@link org.apache.commons.net.ftp.FTPFileListParser}
30   *  to extract the information.
31   * However, most FTP servers return file information in a format that
32   * can be completely parsed by
33   * {@link org.apache.commons.net.ftp.DefaultFTPFileListParser}
34   *  and stored in FTPFile.
35   * <p>
36   * <p>
37   * @author Daniel F. Savarese
38   * @see FTPFileListParser
39   * @see DefaultFTPFileListParser
40   * @see FTPClient#listFiles
41   ***/
42  
43  public class FTPFile implements Serializable
44  {
45      /** A constant indicating an FTPFile is a file. ***/
46      public static final int FILE_TYPE = 0;
47      /** A constant indicating an FTPFile is a directory. ***/
48      public static final int DIRECTORY_TYPE = 1;
49      /** A constant indicating an FTPFile is a symbolic link. ***/
50      public static final int SYMBOLIC_LINK_TYPE = 2;
51      /** A constant indicating an FTPFile is of unknown type. ***/
52      public static final int UNKNOWN_TYPE = 3;
53  
54      /** A constant indicating user access permissions. ***/
55      public static final int USER_ACCESS = 0;
56      /** A constant indicating group access permissions. ***/
57      public static final int GROUP_ACCESS = 1;
58      /** A constant indicating world access permissions. ***/
59      public static final int WORLD_ACCESS = 2;
60  
61      /** A constant indicating file/directory read permission. ***/
62      public static final int READ_PERMISSION = 0;
63      /** A constant indicating file/directory write permission. ***/
64      public static final int WRITE_PERMISSION = 1;
65      /**
66       * A constant indicating file execute permission or directory listing
67       * permission.
68       ***/
69      public static final int EXECUTE_PERMISSION = 2;
70  
71      int _type, _hardLinkCount;
72      long _size;
73      String _rawListing, _user, _group, _name, _link;
74      Calendar _date;
75      boolean[] _permissions[];
76  
77      /*** Creates an empty FTPFile. ***/
78      public FTPFile()
79      {
80          _permissions = new boolean[3][3];
81          _rawListing = null;
82          _type = UNKNOWN_TYPE;
83          _hardLinkCount = 0;
84          _size = 0;
85          _user = null;
86          _group = null;
87          _date = null;
88          _name = null;
89      }
90  
91  
92      /***
93       * Set the original FTP server raw listing from which the FTPFile was
94       * created.
95       * <p>
96       * @param rawListing  The raw FTP server listing.
97       ***/
98      public void setRawListing(String rawListing)
99      {
100         _rawListing = rawListing;
101     }
102 
103     /***
104      * Get the original FTP server raw listing used to initialize the FTPFile.
105      * <p>
106      * @return The original FTP server raw listing used to initialize the
107      *         FTPFile.
108      ***/
109     public String getRawListing()
110     {
111         return _rawListing;
112     }
113 
114 
115     /***
116      * Determine if the file is a directory.
117      * <p>
118      * @return True if the file is of type <code>DIRECTORY_TYPE</code>, false if
119      *         not.
120      ***/
121     public boolean isDirectory()
122     {
123         return (_type == DIRECTORY_TYPE);
124     }
125 
126     /***
127      * Determine if the file is a regular file.
128      * <p>
129      * @return True if the file is of type <code>FILE_TYPE</code>, false if
130      *         not.
131      ***/
132     public boolean isFile()
133     {
134         return (_type == FILE_TYPE);
135     }
136 
137     /***
138      * Determine if the file is a symbolic link.
139      * <p>
140      * @return True if the file is of type <code>UNKNOWN_TYPE</code>, false if
141      *         not.
142      ***/
143     public boolean isSymbolicLink()
144     {
145         return (_type == SYMBOLIC_LINK_TYPE);
146     }
147 
148     /***
149      * Determine if the type of the file is unknown.
150      * <p>
151      * @return True if the file is of type <code>UNKNOWN_TYPE</code>, false if
152      *         not.
153      ***/
154     public boolean isUnknown()
155     {
156         return (_type == UNKNOWN_TYPE);
157     }
158 
159 
160     /***
161      * Set the type of the file (<code>DIRECTORY_TYPE</code>,
162      * <code>FILE_TYPE</code>, etc.).
163      * <p>
164      * @param type  The integer code representing the type of the file.
165      ***/
166     public void setType(int type)
167     {
168         _type = type;
169     }
170 
171 
172     /***
173      * Return the type of the file (one of the <code>_TYPE</code> constants),
174      * e.g., if it is a directory, a regular file, or a symbolic link.
175      * <p>
176      * @return The type of the file.
177      ***/
178     public int getType()
179     {
180         return _type;
181     }
182 
183 
184     /***
185      * Set the name of the file.
186      * <p>
187      * @param name  The name of the file.
188      ***/
189     public void setName(String name)
190     {
191         _name = name;
192     }
193 
194     /***
195      * Return the name of the file.
196      * <p>
197      * @return The name of the file.
198      ***/
199     public String getName()
200     {
201         return _name;
202     }
203 
204 
205     /**
206      * Set the file size in bytes.
207      * @param size The file size in bytes.
208      */
209     public void setSize(long size)
210     {
211         _size = size;
212     }
213 
214 
215     /***
216      * Return the file size in bytes.
217      * <p>
218      * @return The file size in bytes.
219      ***/
220     public long getSize()
221     {
222         return _size;
223     }
224 
225 
226     /***
227      * Set the number of hard links to this file.  This is not to be
228      * confused with symbolic links.
229      * <p>
230      * @param links  The number of hard links to this file.
231      ***/
232     public void setHardLinkCount(int links)
233     {
234         _hardLinkCount = links;
235     }
236 
237 
238     /***
239      * Return the number of hard links to this file.  This is not to be
240      * confused with symbolic links.
241      * <p>
242      * @return The number of hard links to this file.
243      ***/
244     public int getHardLinkCount()
245     {
246         return _hardLinkCount;
247     }
248 
249 
250     /***
251      * Set the name of the group owning the file.  This may be
252      * a string representation of the group number.
253      * <p>
254      * @param group The name of the group owning the file.
255      ***/
256     public void setGroup(String group)
257     {
258         _group = group;
259     }
260 
261 
262     /***
263      * Returns the name of the group owning the file.  Sometimes this will be
264      * a string representation of the group number.
265      * <p>
266      * @return The name of the group owning the file.
267      ***/
268     public String getGroup()
269     {
270         return _group;
271     }
272 
273 
274     /***
275      * Set the name of the user owning the file.  This may be
276      * a string representation of the user number;
277      * <p>
278      * @param user The name of the user owning the file.
279      ***/
280     public void setUser(String user)
281     {
282         _user = user;
283     }
284 
285     /***
286      * Returns the name of the user owning the file.  Sometimes this will be
287      * a string representation of the user number.
288      * <p>
289      * @return The name of the user owning the file.
290      ***/
291     public String getUser()
292     {
293         return _user;
294     }
295 
296 
297     /***
298      * If the FTPFile is a symbolic link, use this method to set the name of the
299      * file being pointed to by the symbolic link.
300      * <p>
301      * @param link  The file pointed to by the symbolic link.
302      ***/
303     public void setLink(String link)
304     {
305         _link = link;
306     }
307 
308 
309     /***
310      * If the FTPFile is a symbolic link, this method returns the name of the
311      * file being pointed to by the symbolic link.  Otherwise it returns null.
312      * <p>
313      * @return The file pointed to by the symbolic link (null if the FTPFile
314      *         is not a symbolic link).
315      ***/
316     public String getLink()
317     {
318         return _link;
319     }
320 
321 
322     /***
323      * Set the file timestamp.  This usually the last modification time.
324      * The parameter is not cloned, so do not alter its value after calling
325      * this method.
326      * <p>
327      * @param date A Calendar instance representing the file timestamp.
328      ***/
329     public void setTimestamp(Calendar date)
330     {
331         _date = date;
332     }
333 
334 
335     /***
336      * Returns the file timestamp.  This usually the last modification time.
337      * <p>
338      * @return A Calendar instance representing the file timestamp.
339      ***/
340     public Calendar getTimestamp()
341     {
342         return _date;
343     }
344 
345 
346     /***
347      * Set if the given access group (one of the <code> _ACCESS </code>
348      * constants) has the given access permission (one of the
349      * <code> _PERMISSION </code> constants) to the file.
350      * <p>
351      * @param access The access group (one of the <code> _ACCESS </code>
352      *               constants)
353      * @param permission The access permission (one of the
354      *               <code> _PERMISSION </code> constants)
355      * @param value  True if permission is allowed, false if not.
356      ***/
357     public void setPermission(int access, int permission, boolean value)
358     {
359         _permissions[access][permission] = value;
360     }
361 
362 
363     /***
364      * Determines if the given access group (one of the <code> _ACCESS </code>
365      * constants) has the given access permission (one of the
366      * <code> _PERMISSION </code> constants) to the file.
367      * <p>
368      * @param access The access group (one of the <code> _ACCESS </code>
369      *               constants)
370      * @param permission The access permission (one of the
371      *               <code> _PERMISSION </code> constants)
372      ***/
373     public boolean hasPermission(int access, int permission)
374     {
375         return _permissions[access][permission];
376     }
377 
378 
379     /***
380      * Returns a string representation of the FTPFile information.  This
381      * will be the raw FTP server listing that was used to initialize the
382      * FTPFile instance.
383      * <p>
384      * @return A string representation of the FTPFile information.
385      ***/
386     @Override
387     public String toString()
388     {
389         return _rawListing;
390     }
391 
392 }