Skip to content
Java library providing rotating/rolling FileOutputStream.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
.travis.yml
COPYING.txt
README.md
pom.xml

README.md

Build Status Maven Central

rotating-fos is a Java 7 library providing RotatingFileOutputStream which internally rotates an underlying FileOutputStream using provided rotation policies similar to Log4j or Logback.

Usage

You first need to include rotating-fos in your Maven/Gradle dependencies:

<dependency>
    <groupId>com.vlkan.rfos</groupId>
    <artifactId>rotating-fos</artifactId>
    <version>${rotating-fos.version}</version>
</dependency>

RotatingFileOutputStream does not extend java.io.FileOutputStream (as a deliberate design decision, see How (not) to extend standard collection classes), but java.io.OutputStream. Its basic usage is pretty straightforward:

RotationConfig config = RotationConfig
        .builder()
        .file("/tmp/app.log")
        .filePattern("/tmp/app-%d{yyyyMMdd-HHmmss.SSS}.log")
        .policy(new SizeBasedRotationPolicy(5000 /* 5s */, 1024 * 1024 * 100 /* 100MB */))
        .policy(DailyRotationPolicy.getInstance())
        .build();

try (RotatingFileOutputStream stream = new RotatingFileOutputStream(config)) {
    stream.writer("Hello, world!".getBytes(StandardCharsets.UTF_8))
}

RotationConfig.Builder supports the following methods:

Method(s) Default Description
file(File)
file(String)
N/A file accessed (e.g., /tmp/app.log)
filePattern(RotatingFilePattern)
filePattern(String)
N/A rotated file pattern (e.g., /tmp/app-%d{yyyyMMdd-HHmmss-SSS}.log)
policy(RotationPolicy)
policies(Set<RotationPolicy> policies)
N/A rotation policies
timer(Timer) Timer timer for scheduling policies
lock(ReadWriteLock) ReentrantReadWriteLock lock for synchronizing stream access (incl. rotations)
append(boolean) true append while opening the file
compress(boolean) false GZIP compression after rotation
clock(Clock) SystemClock clock for retrieving date and time
callback(RotationCallback) LoggingRotationCallback rotation callback

Packaged rotation policies are listed below. (You can also create your own rotation policies by implementing RotationPolicy interface.)

  • DailyRotationPolicy
  • WeeklyRotationPolicy
  • SizeBasedRotationPolicy

Once you have a handle on RotatingFileOutputStream, in addition to standard java.io.OutputStream methods (e.g., write(), close(), etc.), it provides the following methods:

Method Description
RotationConfig getConfig() used configuration
List<Thread> getRunningThreads() compression threads running in the background

Caveats

  • Rotated file conflicts are not resolved by rotating-fos. Once a rotation policy gets triggered, rotating-fos applies the given filePattern to determine the rotated file name. In order to avoid previously generated files to be overridden, prefer a sufficiently fine-grained date-time pattern.

    For instance, given filePattern is /tmp/app-%d{yyyyMMdd}.log, if SizeBasedRotationPolicy gets triggered multiple times within a day, the last one will override the earlier generations in the same day. In order to avoid this, you should have been using a date-time pattern with a higher resolution, such as /tmp/app-%d{yyyyMMdd-HHmmss-SSS}.log.

  • Make sure RotationCallback methods are not blocking. Callbacks are invoked using the Timer thread passed via RotationConfig. Hence blocking callback methods are going to block Timer thread too.

  • Conflicting rotations are discarded. When a rotation gets triggered while one is still in progress, the latter will be discarded. (Conflicts are acknowledged via RotationCallback#onConflict method.)

Contributors

License

Copyright © 2017 Volkan Yazıcı

rotating-fos is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

rotating-fos is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

You can’t perform that action at this time.