hudson.util

Class TextFile

java.lang.Object

hudson.util.TextFile

Direct Known Subclasses:

CallableRejectionConfig

public class TextFile
extends Object

Represents a text file. Provides convenience methods for reading and writing to it.

Author:

Kohsuke Kawaguchi

Field Summary

Fields

Modifier and Type	Field and Description
File	file

Constructor Summary

Constructors

Constructor and Description
TextFile(File file)

Method Summary

Modifier and Type	Method and Description
void	delete()
boolean	exists()
String	fastTail(int numChars) Uses the platform default encoding.
String	fastTail(int numChars, Charset cs) Efficiently reads the last N characters (or shorter, if the whole file is shorter than that.)
String	head(int numChars) Reads the first N characters or until we hit EOF.
Iterable<String>	lines() Deprecated. This method does not properly propagate errors and may lead to file descriptor leaks if the collection is not fully iterated. Use lines2() instead.
Stream<String>	lines2() Read all lines from the file as a Stream.
LinesStream	linesStream() Deprecated. use lines2()
String	read() Reads the entire contents and returns it.
String	readTrim()
String	toString()
void	write(String text) Overwrites the file by the given string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

file

@NonNull
public final File file

Constructor Detail

TextFile

public TextFile(@NonNull
                File file)

Method Detail

exists

public boolean exists()

delete

public void delete()

read

public String read()
            throws IOException

Reads the entire contents and returns it.

Throws:

IOException

lines

@Deprecated
 @NonNull
public Iterable<String> lines()

Deprecated. This method does not properly propagate errors and may lead to file descriptor leaks if the collection is not fully iterated. Use lines2() instead.

Throws:

RuntimeException - in the case of IOException in linesStream()

lines2

@NonNull
public Stream<String> lines2()
                               throws IOException

Read all lines from the file as a Stream. Bytes from the file are decoded into characters using the UTF-8 charset. If timely disposal of file system resources is required, the try-with-resources construct should be used to ensure that BaseStream.close() is invoked after the stream operations are completed.

Returns:

the lines from the file as a Stream

Throws:

IOException - if an I/O error occurs opening the file

linesStream

@CreatesObligation
 @Deprecated
 @NonNull
public LinesStream linesStream()
                                                                  throws IOException

Deprecated. use lines2()

Creates a new LinesStream of the file.

Note: The caller is responsible for closing the returned LinesStream.

Throws:

IOException - if the file cannot be converted to a Path or if the file cannot be opened for reading

Since:

2.111

write

public void write(String text)
           throws IOException

Overwrites the file by the given string.

Throws:

IOException

head

@NonNull
public String head(int numChars)
                     throws IOException

Reads the first N characters or until we hit EOF.

Throws:

IOException

fastTail

@NonNull
public String fastTail(int numChars,
                                Charset cs)
                         throws IOException

Efficiently reads the last N characters (or shorter, if the whole file is shorter than that.)

This method first tries to just read the tail section of the file to get the necessary chars. To handle multi-byte variable length encoding (such as UTF-8), we read a larger than necessary chunk.

Some multi-byte encoding, such as Shift-JIS (http://en.wikipedia.org/wiki/Shift_JIS) doesn't allow the first byte and the second byte of a single char to be unambiguously identified, so it is possible that we end up decoding incorrectly if we start reading in the middle of a multi-byte character. All the CJK multi-byte encodings that I know of are self-correcting; as they are ASCII-compatible, any ASCII characters or control characters will bring the decoding back in sync, so the worst case we just have some garbage in the beginning that needs to be discarded. To accommodate this, we read additional 1024 bytes.

Other encodings, such as UTF-8, are better in that the character boundary is unambiguous, so there can be at most one garbage char. For dealing with UTF-16 and UTF-32, we read at 4 bytes boundary (all the constants and multipliers are multiples of 4.)

Note that it is possible to construct a contrived input that fools this algorithm, and in this method we are willing to live with a small possibility of that to avoid reading the whole text. In practice, such an input is very unlikely.

So all in all, this algorithm should work decently, and it works quite efficiently on a large text.

Throws:

IOException

fastTail

@NonNull
public String fastTail(int numChars)
                         throws IOException

Uses the platform default encoding.

Throws:

IOException

readTrim

public String readTrim()
                throws IOException

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object