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  import java.util.Formatter;
22  
23  /***
24   * The FTPFile class is used to represent information about files stored
25   * on an FTP server.
26   * <p>
27   * <p>
28   * @see FTPFileEntryParser
29   * @see FTPClient#listFiles
30   ***/
31  
32  public class FTPFile implements Serializable
33  {
34      private static final long serialVersionUID = 9010790363003271996L;
35  
36      /** A constant indicating an FTPFile is a file. ***/
37      public static final int FILE_TYPE = 0;
38      /** A constant indicating an FTPFile is a directory. ***/
39      public static final int DIRECTORY_TYPE = 1;
40      /** A constant indicating an FTPFile is a symbolic link. ***/
41      public static final int SYMBOLIC_LINK_TYPE = 2;
42      /** A constant indicating an FTPFile is of unknown type. ***/
43      public static final int UNKNOWN_TYPE = 3;
44  
45      /** A constant indicating user access permissions. ***/
46      public static final int USER_ACCESS = 0;
47      /** A constant indicating group access permissions. ***/
48      public static final int GROUP_ACCESS = 1;
49      /** A constant indicating world access permissions. ***/
50      public static final int WORLD_ACCESS = 2;
51  
52      /** A constant indicating file/directory read permission. ***/
53      public static final int READ_PERMISSION = 0;
54      /** A constant indicating file/directory write permission. ***/
55      public static final int WRITE_PERMISSION = 1;
56      /**
57       * A constant indicating file execute permission or directory listing
58       * permission.
59       ***/
60      public static final int EXECUTE_PERMISSION = 2;
61  
62      private int _type, _hardLinkCount;
63      private long _size;
64      private String _rawListing, _user, _group, _name, _link;
65      private Calendar _date;
66      private final boolean[] _permissions[]; // e.g. _permissions[USER_ACCESS][READ_PERMISSION]
67  
68      /*** Creates an empty FTPFile. ***/
69      public FTPFile()
70      {
71          _permissions = new boolean[3][3];
72          _rawListing = null;
73          _type = UNKNOWN_TYPE;
74          // init these to values that do not occur in listings
75          // so can distinguish which fields are unset
76          _hardLinkCount = 0; // 0 is invalid as a link count
77          _size = -1; // 0 is valid, so use -1
78          _user = "";
79          _group = "";
80          _date = null;
81          _name = null;
82      }
83  
84  
85      /***
86       * Set the original FTP server raw listing from which the FTPFile was
87       * created.
88       * <p>
89       * @param rawListing  The raw FTP server listing.
90       ***/
91      public void setRawListing(String rawListing)
92      {
93          _rawListing = rawListing;
94      }
95  
96      /***
97       * Get the original FTP server raw listing used to initialize the FTPFile.
98       * <p>
99       * @return The original FTP server raw listing used to initialize the
100      *         FTPFile.
101      ***/
102     public String getRawListing()
103     {
104         return _rawListing;
105     }
106 
107 
108     /***
109      * Determine if the file is a directory.
110      * <p>
111      * @return True if the file is of type <code>DIRECTORY_TYPE</code>, false if
112      *         not.
113      ***/
114     public boolean isDirectory()
115     {
116         return (_type == DIRECTORY_TYPE);
117     }
118 
119     /***
120      * Determine if the file is a regular file.
121      * <p>
122      * @return True if the file is of type <code>FILE_TYPE</code>, false if
123      *         not.
124      ***/
125     public boolean isFile()
126     {
127         return (_type == FILE_TYPE);
128     }
129 
130     /***
131      * Determine if the file is a symbolic link.
132      * <p>
133      * @return True if the file is of type <code>UNKNOWN_TYPE</code>, false if
134      *         not.
135      ***/
136     public boolean isSymbolicLink()
137     {
138         return (_type == SYMBOLIC_LINK_TYPE);
139     }
140 
141     /***
142      * Determine if the type of the file is unknown.
143      * <p>
144      * @return True if the file is of type <code>UNKNOWN_TYPE</code>, false if
145      *         not.
146      ***/
147     public boolean isUnknown()
148     {
149         return (_type == UNKNOWN_TYPE);
150     }
151 
152 
153     /***
154      * Set the type of the file (<code>DIRECTORY_TYPE</code>,
155      * <code>FILE_TYPE</code>, etc.).
156      * <p>
157      * @param type  The integer code representing the type of the file.
158      ***/
159     public void setType(int type)
160     {
161         _type = type;
162     }
163 
164 
165     /***
166      * Return the type of the file (one of the <code>_TYPE</code> constants),
167      * e.g., if it is a directory, a regular file, or a symbolic link.
168      * <p>
169      * @return The type of the file.
170      ***/
171     public int getType()
172     {
173         return _type;
174     }
175 
176 
177     /***
178      * Set the name of the file.
179      * <p>
180      * @param name  The name of the file.
181      ***/
182     public void setName(String name)
183     {
184         _name = name;
185     }
186 
187     /***
188      * Return the name of the file.
189      * <p>
190      * @return The name of the file.
191      ***/
192     public String getName()
193     {
194         return _name;
195     }
196 
197 
198     /**
199      * Set the file size in bytes.
200      * @param size The file size in bytes.
201      */
202     public void setSize(long size)
203     {
204         _size = size;
205     }
206 
207 
208     /***
209      * Return the file size in bytes.
210      * <p>
211      * @return The file size in bytes.
212      ***/
213     public long getSize()
214     {
215         return _size;
216     }
217 
218 
219     /***
220      * Set the number of hard links to this file.  This is not to be
221      * confused with symbolic links.
222      * <p>
223      * @param links  The number of hard links to this file.
224      ***/
225     public void setHardLinkCount(int links)
226     {
227         _hardLinkCount = links;
228     }
229 
230 
231     /***
232      * Return the number of hard links to this file.  This is not to be
233      * confused with symbolic links.
234      * <p>
235      * @return The number of hard links to this file.
236      ***/
237     public int getHardLinkCount()
238     {
239         return _hardLinkCount;
240     }
241 
242 
243     /***
244      * Set the name of the group owning the file.  This may be
245      * a string representation of the group number.
246      * <p>
247      * @param group The name of the group owning the file.
248      ***/
249     public void setGroup(String group)
250     {
251         _group = group;
252     }
253 
254 
255     /***
256      * Returns the name of the group owning the file.  Sometimes this will be
257      * a string representation of the group number.
258      * <p>
259      * @return The name of the group owning the file.
260      ***/
261     public String getGroup()
262     {
263         return _group;
264     }
265 
266 
267     /***
268      * Set the name of the user owning the file.  This may be
269      * a string representation of the user number;
270      * <p>
271      * @param user The name of the user owning the file.
272      ***/
273     public void setUser(String user)
274     {
275         _user = user;
276     }
277 
278     /***
279      * Returns the name of the user owning the file.  Sometimes this will be
280      * a string representation of the user number.
281      * <p>
282      * @return The name of the user owning the file.
283      ***/
284     public String getUser()
285     {
286         return _user;
287     }
288 
289 
290     /***
291      * If the FTPFile is a symbolic link, use this method to set the name of the
292      * file being pointed to by the symbolic link.
293      * <p>
294      * @param link  The file pointed to by the symbolic link.
295      ***/
296     public void setLink(String link)
297     {
298         _link = link;
299     }
300 
301 
302     /***
303      * If the FTPFile is a symbolic link, this method returns the name of the
304      * file being pointed to by the symbolic link.  Otherwise it returns null.
305      * <p>
306      * @return The file pointed to by the symbolic link (null if the FTPFile
307      *         is not a symbolic link).
308      ***/
309     public String getLink()
310     {
311         return _link;
312     }
313 
314 
315     /***
316      * Set the file timestamp.  This usually the last modification time.
317      * The parameter is not cloned, so do not alter its value after calling
318      * this method.
319      * <p>
320      * @param date A Calendar instance representing the file timestamp.
321      ***/
322     public void setTimestamp(Calendar date)
323     {
324         _date = date;
325     }
326 
327 
328     /***
329      * Returns the file timestamp.  This usually the last modification time.
330      * <p>
331      * @return A Calendar instance representing the file timestamp.
332      ***/
333     public Calendar getTimestamp()
334     {
335         return _date;
336     }
337 
338 
339     /***
340      * Set if the given access group (one of the <code> _ACCESS </code>
341      * constants) has the given access permission (one of the
342      * <code> _PERMISSION </code> constants) to the file.
343      * <p>
344      * @param access The access group (one of the <code> _ACCESS </code>
345      *               constants)
346      * @param permission The access permission (one of the
347      *               <code> _PERMISSION </code> constants)
348      * @param value  True if permission is allowed, false if not.
349      ***/
350     public void setPermission(int access, int permission, boolean value)
351     {
352         _permissions[access][permission] = value;
353     }
354 
355 
356     /***
357      * Determines if the given access group (one of the <code> _ACCESS </code>
358      * constants) has the given access permission (one of the
359      * <code> _PERMISSION </code> constants) to the file.
360      * <p>
361      * @param access The access group (one of the <code> _ACCESS </code>
362      *               constants)
363      * @param permission The access permission (one of the
364      *               <code> _PERMISSION </code> constants)
365      ***/
366     public boolean hasPermission(int access, int permission)
367     {
368         return _permissions[access][permission];
369     }
370 
371     /***
372      * Returns a string representation of the FTPFile information.
373      *
374      * @return A string representation of the FTPFile information.
375      */
376     @Override
377     public String toString()
378     {
379         return getRawListing();
380     }
381 
382     /***
383      * Returns a string representation of the FTPFile information.
384      * This currently mimics the Unix listing format.
385      *
386      * @return A string representation of the FTPFile information.
387      * @since 3.0
388      */
389     public String toFormattedString()
390     {
391         StringBuilder sb = new StringBuilder();
392         Formatter fmt = new Formatter(sb);
393         sb.append(formatType());
394         sb.append(permissionToString(USER_ACCESS));
395         sb.append(permissionToString(GROUP_ACCESS));
396         sb.append(permissionToString(WORLD_ACCESS));
397         fmt.format(" %4d", Integer.valueOf(getHardLinkCount()));
398         fmt.format(" %-8s %-8s", getGroup(), getUser());
399         fmt.format(" %8d", Long.valueOf(getSize()));
400         Calendar timestamp = getTimestamp();
401         if (timestamp != null) {
402             fmt.format(" %1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS", timestamp);
403             fmt.format(" %1$tZ", timestamp);
404             sb.append(' ');
405         }
406         sb.append(' ');
407         sb.append(getName());
408         fmt.close();
409         return sb.toString();
410     }
411 
412     private char formatType(){
413         switch(_type) {
414             case FILE_TYPE:
415                 return '-';
416             case DIRECTORY_TYPE:
417                 return 'd';
418             case SYMBOLIC_LINK_TYPE:
419                 return 'l';
420         }
421         return '?';
422     }
423 
424     private String permissionToString(int access ){
425         StringBuilder sb = new StringBuilder();
426         if (hasPermission(access, READ_PERMISSION)) {
427             sb.append('r');
428         } else {
429             sb.append('-');
430         }
431         if (hasPermission(access, WRITE_PERMISSION)) {
432             sb.append('w');
433         } else {
434             sb.append('-');
435         }
436         if (hasPermission(access, EXECUTE_PERMISSION)) {
437             sb.append('x');
438         } else {
439             sb.append('-');
440         }
441         return sb.toString();
442     }
443 }