View Javadoc

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