wnameless / spring-paper-trail

Add automatic audit trail to all stateful HTTP requests by the annotation @EnablePaperTrail

spring-paper-trail

Add automatic audit trail to all stateful HTTP requests by the annotation @EnablePaperTrail

Purpose

Log essential information about any stateful request which includes:

1. User ID: the user name
   
2. Remote Address: the user IP address
   
3. HTTP Method: POST, DELETE, PUT or PATCH
   
4. Request URI: the URI of user request
   
5. HTTP status: status code, ex: 201, 404
   
6. Timestamp: the date and time of this paper trail

Features

1. Supports all kinds of databases
2. Provides callbacks for sophisticated operations

Maven Repo

<dependency>
	<groupId>com.github.wnameless.spring</groupId>
	<artifactId>spring-paper-trail</artifactId>
	<version>0.3.0</version>
</dependency>

Quick Start

Add @EnablePaperTrail to enable paper trail,
JpaPaperTrail.class is an entity class which implements the PaperTrail interface

@Configuration
@EnablePaperTrail(JpaPaperTrail.class)
public class WebConfig {
  ...
}

JPA example:

@Entity
public class JpaPaperTrail extends AbstractJpaPaperTrail {}

AbstractJpaPaperTrail is a convenient abstract class for JPA PaperTrail

Don't forget to provide a PaperTrailCrudRepository for any PaperTrail entity you just created

public interface PaperTrailJpaRepository
    extends PaperTrailCrudRepository<JpaPaperTrail, Long> {}

MongoDB example:

@Entity
public class MongoPaperTrail extends AbstractPaperTrail {
  @Id private String id;
}

or

@Entity
public class MongoPaperTrail implements PaperTrail {
  ...
}

FYI, AbstractMongoPaperTrail is also provided in this library

Again, don't forget the PaperTrailCrudRepository

public interface PaperTrailMongoRepository
    extends PaperTrailCrudRepository<MongoPaperTrail, String> {}

That's all you need!

Advanced Usage

By default, spring-paper-trail only log the POST, DELETE, PUT and PATCH methods,
however you can change its behavior by doing this:

@EnablePaperTrail(value=JpaPaperTrail.class, targetMethods={HttpMethod.GET, HttpMethod.POST})

The user ID is retrieved by the HttpServletRequest#getUserPrincipal,
but you can override this mechanism by providing a PaperTrailUserIdStrategy bean:

@Bean
public PaperTrailUserIdStrategy paperTrailUserIdStrategy() {
  return new PaperTrailUserIdStrategy(HttpServletRequest request) {
    public String getUserId() {...}
  };
}

If you wish to use the paper trail information to do more things,
there are callbacks you can use:

@Bean
public BeforePaperTrailCallback<JpaPaperTrail> beforePaperTrailCallback() {
  return new beforePaperTrailCallback<JpaPaperTrail>() {
    public void beforePaperTrail(JpaPaperTrail paperTrail,
        HttpServletRequest request, HttpServletResponse response) {...}
  };
}

@Bean
public AfterPaperTrailCallback<JpaPaperTrail> afterPaperTrailCallback() {
  return new AfterPaperTrailCallback<JpaPaperTrail>() {
    public void afterPaperTrail(JpaPaperTrail paperTrail,
        HttpServletRequest request, HttpServletResponse response) {...}
  };
}

@Bean
public AroundPaperTrailCallback<JpaPaperTrail, PaperTrailJpaRepository> aroundTrailCallback() {
  return new AroundPaperTrailCallback<JpaPaperTrail, PaperTrailJpaRepository>() {
      public void aroundPaperTrail(PaperTrailJpaRepository paperTrailRepo,
          JpaPaperTrail paperTrail, HttpServletRequest request,
          HttpServletResponse response) {
          ...
          paperTrailRepo.save(paperTrail);
          ...
      }
  };
}

// It's deprecated since v0.3.0
@Bean
public PaperTrailCallback<JpaPaperTrail> paperTrailCallback() {
  return new PaperTrailCallback<JpaPaperTrail>() {
    public void doWithPaperTrail(JpaPaperTrail paperTrail,
        HttpServletRequest request, HttpServletResponse response) {...}
  };
}