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.ftp;
019
020import java.io.Serializable;
021import java.time.Instant;
022import java.util.Calendar;
023import java.util.Date;
024import java.util.Formatter;
025import java.util.TimeZone;
026
027/**
028 * The FTPFile class is used to represent information about files stored on an FTP server.
029 *
030 * @see FTPFileEntryParser
031 * @see FTPClient#listFiles
032 */
033public class FTPFile implements Serializable {
034
035    private static final long serialVersionUID = 9010790363003271996L;
036
037    /** A constant indicating an FTPFile is a file. */
038    public static final int FILE_TYPE = 0;
039
040    /** A constant indicating an FTPFile is a directory. */
041    public static final int DIRECTORY_TYPE = 1;
042
043    /** A constant indicating an FTPFile is a symbolic link. */
044    public static final int SYMBOLIC_LINK_TYPE = 2;
045
046    /** A constant indicating an FTPFile is of unknown type. */
047    public static final int UNKNOWN_TYPE = 3;
048
049    /** A constant indicating user access permissions. */
050    public static final int USER_ACCESS = 0;
051
052    /** A constant indicating group access permissions. */
053    public static final int GROUP_ACCESS = 1;
054
055    /** A constant indicating world access permissions. */
056    public static final int WORLD_ACCESS = 2;
057
058    /** A constant indicating file/directory read permission. */
059    public static final int READ_PERMISSION = 0;
060
061    /** A constant indicating file/directory write permission. */
062    public static final int WRITE_PERMISSION = 1;
063
064    /** A constant indicating file execute permission or directory listing permission. */
065    public static final int EXECUTE_PERMISSION = 2;
066
067    private int type = UNKNOWN_TYPE;
068
069    /** 0 is invalid as a link count. */
070    private int hardLinkCount;
071
072    /** 0 is valid, so use -1. */
073    private long size = -1;
074    private String rawListing;
075    private String user = "";
076    private String group = "";
077    private String name;
078    private String link;
079
080    // TODO Consider changing internal representation to java.time.
081    private Calendar calendar;
082
083    /** If this is null, then list entry parsing failed. */
084    private final boolean[][] permissions; // e.g. _permissions[USER_ACCESS][READ_PERMISSION]
085
086    /** Creates an empty FTPFile. */
087    public FTPFile() {
088        permissions = new boolean[3][3];
089    }
090
091    /**
092     * Constructor for use by {@link FTPListParseEngine} only. Used to create FTPFile entries for failed parses
093     *
094     * @param rawListing line that could not be parsed.
095     * @since 3.4
096     */
097    FTPFile(final String rawListing) {
098        this.permissions = null; // flag that entry is invalid
099        this.rawListing = rawListing;
100    }
101
102    private char formatType() {
103        switch (type) {
104        case FILE_TYPE:
105            return '-';
106        case DIRECTORY_TYPE:
107            return 'd';
108        case SYMBOLIC_LINK_TYPE:
109            return 'l';
110        default:
111            return '?';
112        }
113    }
114
115    /**
116     * Gets the name of the group owning the file. Sometimes this will be a string representation of the group number.
117     *
118     * @return The name of the group owning the file.
119     */
120    public String getGroup() {
121        return group;
122    }
123
124    /**
125     * Gets the number of hard links to this file. This is not to be confused with symbolic links.
126     *
127     * @return The number of hard links to this file.
128     */
129    public int getHardLinkCount() {
130        return hardLinkCount;
131    }
132
133    /**
134     * If the FTPFile is a symbolic link, this method returns the name of the file being pointed to by the symbolic link.
135     * Otherwise, it returns {@code null}.
136     *
137     * @return The file pointed to by the symbolic link ({@code null} if the FTPFile is not a symbolic link).
138     */
139    public String getLink() {
140        return link;
141    }
142
143    /**
144     * Gets the name of the file.
145     *
146     * @return The name of the file.
147     */
148    public String getName() {
149        return name;
150    }
151
152    /**
153     * Gets the original FTP server raw listing used to initialize the FTPFile.
154     *
155     * @return The original FTP server raw listing used to initialize the FTPFile.
156     */
157    public String getRawListing() {
158        return rawListing;
159    }
160
161    /**
162     * Gets the file size in bytes.
163     *
164     * @return The file size in bytes.
165     */
166    public long getSize() {
167        return size;
168    }
169
170    /**
171     * Gets the file timestamp. This usually the last modification time.
172     *
173     * @return A Calendar instance representing the file timestamp.
174     */
175    public Calendar getTimestamp() {
176        return calendar;
177    }
178
179    /**
180     * Gets the file timestamp. This usually the last modification time.
181     *
182     * @return A Calendar instance representing the file timestamp.
183     * @since 3.9.0
184     */
185    public Instant getTimestampInstant() {
186        return calendar == null ? null : calendar.toInstant();
187    }
188
189    /**
190     * Gets the type of the file (one of the {@code _TYPE} constants), e.g., if it is a directory, a regular file, or a symbolic link.
191     *
192     * @return The type of the file.
193     */
194    public int getType() {
195        return type;
196    }
197
198    /**
199     * Gets the name of the user owning the file. Sometimes this will be a string representation of the user number.
200     *
201     * @return The name of the user owning the file.
202     */
203    public String getUser() {
204        return user;
205    }
206
207    /**
208     * Tests if the given access group (one of the {@code _ACCESS} constants) has the given access permission (one of the {@code _PERMISSION}
209     * constants) to the file.
210     *
211     * @param access     The access group (one of the {@code _ACCESS} constants)
212     * @param permission The access permission (one of the {@code _PERMISSION} constants)
213     * @throws ArrayIndexOutOfBoundsException if either of the parameters is out of range
214     * @return {@code true} if {@link #isValid()} is {@code true} and the associated permission is set; {@code false} otherwise.
215     */
216    public boolean hasPermission(final int access, final int permission) {
217        if (permissions == null) {
218            return false;
219        }
220        return permissions[access][permission];
221    }
222
223    /**
224     * Tests if the file is a directory.
225     *
226     * @return {@code true} if the file is of type {@code DIRECTORY_TYPE}, {@code false} if not.
227     */
228    public boolean isDirectory() {
229        return type == DIRECTORY_TYPE;
230    }
231
232    /**
233     * Tests if the file is a regular file.
234     *
235     * @return {@code true} if the file is of type {@code FILE_TYPE}, {@code false} if not.
236     */
237    public boolean isFile() {
238        return type == FILE_TYPE;
239    }
240
241    /**
242     * Tests if the file is a symbolic link.
243     *
244     * @return {@code true} if the file is of type {@code SYMBOLIC_LINK_TYPE}, {@code false} if not.
245     */
246    public boolean isSymbolicLink() {
247        return type == SYMBOLIC_LINK_TYPE;
248    }
249
250    /**
251     * Tests if the type of the file is unknown.
252     *
253     * @return {@code true} if the file is of type {@code UNKNOWN_TYPE}, {@code false} if not.
254     */
255    public boolean isUnknown() {
256        return type == UNKNOWN_TYPE;
257    }
258
259    /**
260     * Tests whether an entry is valid or not. If the entry is invalid, only the {@link #getRawListing()} method will be useful. Other methods may fail.
261     *
262     * Used in conjunction with list parsing that preserves entries that failed to parse.
263     *
264     * @see FTPClientConfig#setUnparseableEntries(boolean)
265     * @return {@code true} if the entry is valid; {@code false} otherwise
266     * @since 3.4
267     */
268    public boolean isValid() {
269        return permissions != null;
270    }
271
272    private String permissionToString(final int access) {
273        final StringBuilder sb = new StringBuilder();
274        if (hasPermission(access, READ_PERMISSION)) {
275            sb.append('r');
276        } else {
277            sb.append('-');
278        }
279        if (hasPermission(access, WRITE_PERMISSION)) {
280            sb.append('w');
281        } else {
282            sb.append('-');
283        }
284        if (hasPermission(access, EXECUTE_PERMISSION)) {
285            sb.append('x');
286        } else {
287            sb.append('-');
288        }
289        return sb.toString();
290    }
291
292    private void readObject(final java.io.ObjectInputStream in) {
293        throw new UnsupportedOperationException("Serialization is not supported");
294    }
295
296    /**
297     * Sets the name of the group owning the file. This may be a string representation of the group number.
298     *
299     * @param group The name of the group owning the file.
300     */
301    public void setGroup(final String group) {
302        this.group = group;
303    }
304
305    /**
306     * Sets the number of hard links to this file. This is not to be confused with symbolic links.
307     *
308     * @param links The number of hard links to this file.
309     */
310    public void setHardLinkCount(final int links) {
311        this.hardLinkCount = links;
312    }
313
314    /**
315     * If the FTPFile is a symbolic link, use this method to set the name of the file being pointed to by the symbolic link.
316     *
317     * @param link The file pointed to by the symbolic link.
318     */
319    public void setLink(final String link) {
320        this.link = link;
321    }
322
323    /**
324     * Sets the name of the file.
325     *
326     * @param name The name of the file.
327     */
328    public void setName(final String name) {
329        this.name = name;
330    }
331
332    /**
333     * Sets if the given access group (one of the {@code _ACCESS} constants) has the given access permission (one of the {@code _PERMISSION}
334     * constants) to the file.
335     *
336     * @param access     The access group (one of the {@code _ACCESS} constants)
337     * @param permission The access permission (one of the {@code _PERMISSION} constants)
338     * @param value      {@code true} if permission is allowed, {@code false} if not.
339     * @throws ArrayIndexOutOfBoundsException if either of the parameters is out of range
340     */
341    public void setPermission(final int access, final int permission, final boolean value) {
342        // TODO: only allow permission setting if file is valid
343        permissions[access][permission] = value;
344    }
345
346    /**
347     * Sets the original FTP server raw listing from which the FTPFile was created.
348     *
349     * @param rawListing The raw FTP server listing.
350     */
351    public void setRawListing(final String rawListing) {
352        this.rawListing = rawListing;
353    }
354
355    /**
356     * Sets the file size in bytes.
357     *
358     * @param size The file size in bytes.
359     */
360    public void setSize(final long size) {
361        this.size = size;
362    }
363
364    /**
365     * Sets the file timestamp. This usually the last modification time. The parameter is not cloned, so do not alter its value after calling this method.
366     *
367     * @param date A Calendar instance representing the file timestamp.
368     */
369    public void setTimestamp(final Calendar date) {
370        this.calendar = date;
371    }
372
373    /**
374     * Sets the type of the file ({@code DIRECTORY_TYPE}, {@code FILE_TYPE}, etc.).
375     *
376     * @param type The integer code representing the type of the file.
377     */
378    public void setType(final int type) {
379        this.type = type;
380    }
381
382    /**
383     * Sets the name of the user owning the file. This may be a string representation of the user number;
384     *
385     * @param user The name of the user owning the file.
386     */
387    public void setUser(final String user) {
388        this.user = user;
389    }
390
391    /**
392     * Gets a string representation of the FTPFile information. This currently mimics the UNIX listing format. This method uses the time zone of the Calendar
393     * entry, which is the server time zone (if one was provided) otherwise it is the local time zone.
394     * <p>
395     * Note: if the instance is not valid {@link #isValid()}, no useful information can be returned. In this case, use {@link #getRawListing()} instead.
396     * </p>
397     *
398     * @return A string representation of the FTPFile information.
399     * @since 3.0
400     */
401    public String toFormattedString() {
402        return toFormattedString(null);
403    }
404
405    /**
406     * Gets a string representation of the FTPFile information. This currently mimics the UNIX listing format. This method allows the Calendar time zone to be
407     * overridden.
408     * <p>
409     * Note: if the instance is not valid {@link #isValid()}, no useful information can be returned. In this case, use {@link #getRawListing()} instead.
410     * </p>
411     *
412     * @param timezone the time zone to use for displaying the time stamp If {@code null}, then use the Calendar ({@link #getTimestamp()}) entry
413     * @return A string representation of the FTPFile information.
414     * @since 3.4
415     */
416    public String toFormattedString(final String timezone) {
417
418        if (!isValid()) {
419            return "[Invalid: could not parse file entry]";
420        }
421        final StringBuilder sb = new StringBuilder();
422        try (final Formatter fmt = new Formatter(sb)) {
423            sb.append(formatType());
424            sb.append(permissionToString(USER_ACCESS));
425            sb.append(permissionToString(GROUP_ACCESS));
426            sb.append(permissionToString(WORLD_ACCESS));
427            fmt.format(" %4d", Integer.valueOf(getHardLinkCount()));
428            fmt.format(" %-8s %-8s", getUser(), getGroup());
429            fmt.format(" %8d", Long.valueOf(getSize()));
430            Calendar timestamp = getTimestamp();
431            if (timestamp != null) {
432                if (timezone != null) {
433                    final TimeZone newZone = TimeZone.getTimeZone(timezone);
434                    if (!newZone.equals(timestamp.getTimeZone())) {
435                        final Date original = timestamp.getTime();
436                        final Calendar newStamp = Calendar.getInstance(newZone);
437                        newStamp.setTime(original);
438                        timestamp = newStamp;
439                    }
440                }
441                fmt.format(" %1$tY-%1$tm-%1$td", timestamp);
442                // Only display time units if they are present
443                if (timestamp.isSet(Calendar.HOUR_OF_DAY)) {
444                    fmt.format(" %1$tH", timestamp);
445                    if (timestamp.isSet(Calendar.MINUTE)) {
446                        fmt.format(":%1$tM", timestamp);
447                        if (timestamp.isSet(Calendar.SECOND)) {
448                            fmt.format(":%1$tS", timestamp);
449                            if (timestamp.isSet(Calendar.MILLISECOND)) {
450                                fmt.format(".%1$tL", timestamp);
451                            }
452                        }
453                    }
454                    fmt.format(" %1$tZ", timestamp);
455                }
456            }
457            sb.append(' ');
458            sb.append(getName());
459        }
460        return sb.toString();
461    }
462
463    /*
464     * Serialization is unnecessary for this class. Reject attempts to do so until such time as the Serializable attribute can be dropped.
465     */
466
467    /**
468     * Gets a string representation of the FTPFile information.
469     * Delegates to {@link #getRawListing()}
470     *
471     * @see #getRawListing()
472     * @return A string representation of the FTPFile information.
473     */
474    @Override
475    public String toString() {
476        return getRawListing();
477    }
478
479    private void writeObject(final java.io.ObjectOutputStream out) {
480        throw new UnsupportedOperationException("Serialization is not supported");
481    }
482
483}