You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@commons.apache.org by GitBox <gi...@apache.org> on 2021/09/06 18:40:47 UTC
[GitHub] [commons-io] garydgregory commented on a change in pull request #32: Introduce Tailable interface to allow tailing of files accessed using alternative libraries such as jCIFS or commons-vfs
garydgregory commented on a change in pull request #32:
URL: https://github.com/apache/commons-io/pull/32#discussion_r703034810
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
+
+ /**
+ * @return The full path of this tailable
+ */
+ String getPath();
+
+ /**
+ * Returns the length of this tailable
+ *
+ * @return The length, in bytes, of this tailable, or <code>0L</code>
+ * if the file does not exist. Some operating systems may
+ * return <code>0L</code> for pathnames denoting system-dependent
+ * entities such as devices or pipes.
+ */
+ long length();
+
+ /**
+ * Returns the time that this tailable was last modified.
+ *
+ * @return A <code>long</code> value representing the time this tailable
+ * was last modified, measured in milliseconds since the epoch
+ * (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
+ * tailable does not exist or if an I/O error occurs
+ */
+ long lastModified() throws IOException;
+
+ /**
+ * Tests whether this tailable exists.
+ *
+ * @return <code>true</code> if and only if the tailable exists;
+ * <code>false</code> otherwise
+ */
+ boolean exists();
+
+ /**
+ * Tests if this tailable is newer than the specified time reference.
+ *
+ * @param timeMillis the time reference measured in milliseconds since the
+ * epoch (00:00:00 GMT, January 1, 1970).
+ * @return true if this tailable has been modified after the given time reference.
+ */
+ boolean isFileNewer(final long timeMillis);
+
+ /**
+ * @param mode the access mode {@link RandomAccessFile}
Review comment:
The 1st sentence is missing for this method.
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
Review comment:
The name of... what? the base file name? The full file name?
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
Review comment:
The 1st sentence is missing for this method.
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
+
+ /**
+ * @return The full path of this tailable
+ */
+ String getPath();
+
+ /**
+ * Returns the length of this tailable
+ *
+ * @return The length, in bytes, of this tailable, or <code>0L</code>
+ * if the file does not exist. Some operating systems may
+ * return <code>0L</code> for pathnames denoting system-dependent
+ * entities such as devices or pipes.
+ */
+ long length();
+
+ /**
+ * Returns the time that this tailable was last modified.
+ *
+ * @return A <code>long</code> value representing the time this tailable
+ * was last modified, measured in milliseconds since the epoch
+ * (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
+ * tailable does not exist or if an I/O error occurs
+ */
+ long lastModified() throws IOException;
+
+ /**
+ * Tests whether this tailable exists.
+ *
+ * @return <code>true</code> if and only if the tailable exists;
+ * <code>false</code> otherwise
+ */
+ boolean exists();
+
+ /**
+ * Tests if this tailable is newer than the specified time reference.
+ *
+ * @param timeMillis the time reference measured in milliseconds since the
+ * epoch (00:00:00 GMT, January 1, 1970).
+ * @return true if this tailable has been modified after the given time reference.
+ */
+ boolean isFileNewer(final long timeMillis);
+
+ /**
+ * @param mode the access mode {@link RandomAccessFile}
+ * @return a random access file stream to read from
+ * @throws FileNotFoundException if the tailable object does not exist
+ */
+ RandomAccessTailable getRandomAccess(final String mode) throws FileNotFoundException;
+ }
+
+ /**
+ * Abstraction on {@link java.io.RandomAccessFile} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface RandomAccessTailable extends Closeable {
+ /**
+ * Returns the current offset in this tailable.
+ *
+ * @return the offset from the beginning of the tailable, in bytes,
+ * at which the next read or write occurs.
+ * @exception IOException if an I/O error occurs.
+ */
+ long getFilePointer() throws IOException;
+
+ /**
+ * Sets the file-pointer offset, measured from the beginning of this
+ * tailable, at which the next read or write occurs. The offset may be
+ * set beyond the end of the tailable. Setting the offset beyond the end
+ * of the tailable does not change the tailable length. The tailable
+ * length will change only by writing after the offset has been set beyond
+ * the end of the tailable.
+ *
+ * @param pos the offset position, measured in bytes from the
+ * beginning of the tailable, at which to set the
+ * tailable pointer.
+ * @exception IOException if {@code pos} is less than
Review comment:
"@exception" -> "@throws"
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
+
+ /**
+ * @return The full path of this tailable
+ */
+ String getPath();
+
+ /**
+ * Returns the length of this tailable
+ *
+ * @return The length, in bytes, of this tailable, or <code>0L</code>
+ * if the file does not exist. Some operating systems may
+ * return <code>0L</code> for pathnames denoting system-dependent
+ * entities such as devices or pipes.
+ */
+ long length();
+
+ /**
+ * Returns the time that this tailable was last modified.
+ *
+ * @return A <code>long</code> value representing the time this tailable
+ * was last modified, measured in milliseconds since the epoch
+ * (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
+ * tailable does not exist or if an I/O error occurs
+ */
+ long lastModified() throws IOException;
+
+ /**
+ * Tests whether this tailable exists.
+ *
+ * @return <code>true</code> if and only if the tailable exists;
+ * <code>false</code> otherwise
+ */
+ boolean exists();
+
+ /**
+ * Tests if this tailable is newer than the specified time reference.
+ *
+ * @param timeMillis the time reference measured in milliseconds since the
+ * epoch (00:00:00 GMT, January 1, 1970).
+ * @return true if this tailable has been modified after the given time reference.
+ */
+ boolean isFileNewer(final long timeMillis);
+
+ /**
+ * @param mode the access mode {@link RandomAccessFile}
+ * @return a random access file stream to read from
+ * @throws FileNotFoundException if the tailable object does not exist
+ */
+ RandomAccessTailable getRandomAccess(final String mode) throws FileNotFoundException;
+ }
+
+ /**
+ * Abstraction on {@link java.io.RandomAccessFile} which allows substitution of remote files for example using jCIFS
Review comment:
Sentences should end in a period.
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
+
+ /**
+ * @return The full path of this tailable
+ */
+ String getPath();
+
+ /**
+ * Returns the length of this tailable
+ *
+ * @return The length, in bytes, of this tailable, or <code>0L</code>
+ * if the file does not exist. Some operating systems may
+ * return <code>0L</code> for pathnames denoting system-dependent
+ * entities such as devices or pipes.
+ */
+ long length();
+
+ /**
+ * Returns the time that this tailable was last modified.
+ *
+ * @return A <code>long</code> value representing the time this tailable
+ * was last modified, measured in milliseconds since the epoch
+ * (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
+ * tailable does not exist or if an I/O error occurs
+ */
+ long lastModified() throws IOException;
+
+ /**
+ * Tests whether this tailable exists.
+ *
+ * @return <code>true</code> if and only if the tailable exists;
+ * <code>false</code> otherwise
+ */
+ boolean exists();
+
+ /**
+ * Tests if this tailable is newer than the specified time reference.
+ *
+ * @param timeMillis the time reference measured in milliseconds since the
+ * epoch (00:00:00 GMT, January 1, 1970).
+ * @return true if this tailable has been modified after the given time reference.
+ */
+ boolean isFileNewer(final long timeMillis);
+
+ /**
+ * @param mode the access mode {@link RandomAccessFile}
+ * @return a random access file stream to read from
+ * @throws FileNotFoundException if the tailable object does not exist
+ */
+ RandomAccessTailable getRandomAccess(final String mode) throws FileNotFoundException;
+ }
+
+ /**
+ * Abstraction on {@link java.io.RandomAccessFile} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface RandomAccessTailable extends Closeable {
+ /**
+ * Returns the current offset in this tailable.
Review comment:
"Returns" -> "Gets"
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
+
+ /**
+ * @return The full path of this tailable
+ */
+ String getPath();
Review comment:
Confusing API name because it does not return a `Path`; either rename the API or make it return a `Path`.
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -556,4 +784,181 @@ private long readLines(final RandomAccessFile reader) throws IOException {
return rePos;
}
}
+
+ /**
+ * Abstraction on {@link java.io.File} which allows substitution of remote files for example using jCIFS
+ *
+ * @since 2.12.0
+ */
+ public interface Tailable {
+ /**
+ * @return The name of the file denoted by this tailable
+ */
+ String getName();
+
+ /**
+ * @return The full path of this tailable
+ */
+ String getPath();
+
+ /**
+ * Returns the length of this tailable
+ *
+ * @return The length, in bytes, of this tailable, or <code>0L</code>
Review comment:
<code>foo</code> -> {@code foo}
##########
File path: src/main/java/org/apache/commons/io/input/Tailer.java
##########
@@ -191,6 +203,18 @@ public Tailer(final File file, final TailerListener listener, final long delayMi
this(file, listener, delayMillis, false);
}
+ /**
Review comment:
There are way too many new factory APIs here IMO. For the first cut, let's add one and see what other use-cases require in the future. If a delay is provided, please make that a `Duration`, not a `long`. I'll redo the internals after this PR comes in to use a Duration instead of a `long`. If you add a constructor, make it private or package private.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@commons.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org