Category Archives: Spring

Testeando y documentando REST WS con Spring REST Docs

El presente post se centra en el uso de Spring REST Docs, un componente de la suite de Spring, que tiene como objetivo facilitar la generación de documentación de servicios web tipo REST.

Esta parte de Spring se integra con Spring MVC Test para que, desde nuestros tests de unidad o de integración, podamos, a la vez que se testean los servicios web, generar una documentación en formato HTML completa, consistente y moderna con la que describir el uso de los mismos.

Qué cocinamos

El uso de servicios web es una buena manera de compartir funcionalidades entre aplicaciones, crear interacciones entre ellas e integrar diferentes usos. Es una manera sencilla y poco invasiva de compartir información y realizar peticiones de ejecución de todo tipo de servicios. Además los servicios web tipo REST son sencillos de implementar, siguen estándares bien definidos y son compatibles entre multitud de aplicaciones y tipos de tecnologías.

Uno de los principales problemas a la hora de compartir o publicar un conjunto de servicios web tipo REST para que puedan ser usados por terceros es documentarlos debidamente para que esas terceras partes conozcan como usarlos, que invocar, que entradas de datos deben usar o que salidas deben esperar. Si otros tipos de servicios similares, como los servicios web tipo SOAP tienen documentos más o menos formales y estandarizados como los WSDL, que pueden ser usados por aplicaciones de terceros para crear clientes que invoquen a nuestros servicios, practicamente de forma automática, en el caso de los servicios tipo REST, su simplicidad y fundamentos basados en tecnologías más genéricas impide o dificulta la presencia de ese tipo de formalismos (aunque existen intentos para definir formalmente este tipo de servicios de forma similar usando también XML).

Al final, lo que parece ser una ventaja del mundo de los WS tipo REST, en relación a su simplicidad, puede verse como un problema a la hora de transmitir su uso a terceros. Por este motivo, se recomiendan, además de usar una serie de estándares o buenas prácticas a la hora de desarrollar los servicios, unas buenas prácticas asimismo a la hora de documentarlos. En este sentido, Spring REST Docs es una herramienta de gran utilidad ya que permite, al mismo tiempo que se testean esos mismos servicios web, generar una documentación de calidad. Además si se siguen esas recomendaciones y buenas prácticas, tendremos una documentación útil y sencilla de transmitir a terceros para que puedan hacer uso de nuestros servicios.

Lo que hace Spring REST Docs es generar, en función de la implementación que establezcamos en su ejecución, que puede realizarse integramente dentros de los tests de unidad o integración de nuestros servicios, una documentación en texto plano que posteriormente se transformará en HTML (u otros formatos) usando un programa externo llamado Asciidoctor. Para facilitar esto, existen plug-ins para Maven que permiten ejecutar los tests y generar la documentación de forma simultánea, de tal manera que incluso si la generación de documentación falla, el test también fallará, asegurándonos así que existe una referencia consistente para ese servicio.

Ingredientes

Vamos a usar una aplicación web de prueba que implementa una serie de servicios web tipo REST para pobar los Spring REST Docs, testeando y documentando dichos servicios de forma simultanea. Para ello necesitaremos:

Spring Boot
Spring MVC
Spring Data
Spring REST Docs
HSQLDB
Log4j

Para más información acerca de las dependencias usadas (versiones, paquetes específicos etc.) se puede echar un vistazo al pom.xml que se incluye con el proyecto.

Paso a paso

Lo de siempre, una vez creado nuestro proyecto, se maveniza. Este es el aspecto del pom.xml que incluye las dependencias a las librerias de los componentes anteriores:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>SpringRestDocs</groupId>
  <artifactId>SpringRestDocs</artifactId>
  <version>1.0</version>

  <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>1.3.1.RELEASE</version>
  </parent>

  <dependencies>
      <!-- Add typical dependencies for a web application -->
      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

      <!-- Add typical dependencies for a spring JPA -->
      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-data-jpa</artifactId>
      </dependency>

      <!-- REST docs and MockMVC dependencies -->
      <dependency>
          <groupId>org.springframework.restdocs</groupId>
          <artifactId>spring-restdocs-mockmvc</artifactId>
          <version>1.0.1.RELEASE</version><!--$NO-MVN-MAN-VER$-->
       </dependency>

      <!-- Add typical dependencies for HSQLDB -->
      <dependency>
          <groupId>org.hsqldb</groupId>
          <artifactId>hsqldb</artifactId>
      </dependency>

      <!-- Use Log4j instead of default logging -->
          <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-logging</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-log4j</artifactId>
        </dependency>
  </dependencies>

  <build>
    <sourceDirectory>src</sourceDirectory>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>

      <!-- Package as an executable jar -->
      <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <configuration>
              <mainClass>net.luisalbertogh.springrestdocs.SpringRestDocs</mainClass>
          </configuration>
      </plugin>

      <!-- Surfire plugin - Plugin to execute Tests -->
      <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-surefire-plugin</artifactId>
          <configuration>
              <includes>
                  <include>**/*Test.java</include>
              </includes>
          </configuration>
      </plugin>

      <!-- Asciidoctor plugin - Plugin for REST documentation -->
      <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.2</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <!-- Configured to include documentation within the executable JAR file -->
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                        <outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <attributes>
                            <snippets>${project.build.directory}/generated-snippets</snippets>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- Resources plugin - Copy generated REST docs into output location to be included within the release -->
        <plugin>
            <artifactId>maven-resources-plugin</artifactId>
            <version>2.7</version><!--$NO-MVN-MAN-VER$-->
            <executions>
                <execution>
                    <id>copy-resources</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>
                            ${project.build.outputDirectory}/static/docs/${project.version}
                        </outputDirectory>
                        <resources>
                            <resource>
                                <directory>
                                    ${project.build.directory}/generated-docs/${project.version}
                                </directory>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
        </plugin>

    </plugins>
  </build>

  <!-- Add Spring repositories -->
  <!-- (you don't need this if you are using a .RELEASE version) -->
  <repositories>
      <repository>
          <id>spring-snapshots</id>
          <url>http://repo.spring.io/snapshot</url>
          <snapshots><enabled>true</enabled></snapshots>
      </repository>
      <repository>
          <id>spring-milestones</id>
          <url>http://repo.spring.io/milestone</url>
      </repository>
  </repositories>
  <pluginRepositories>
      <pluginRepository>
          <id>spring-snapshots</id>
          <url>http://repo.spring.io/snapshot</url>
      </pluginRepository>
      <pluginRepository>
          <id>spring-milestones</id>
          <url>http://repo.spring.io/milestone</url>
      </pluginRepository>
  </pluginRepositories>
</project>

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

<groupId>SpringRestDocs</groupId>

<artifactId>SpringRestDocs</artifactId>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>1.3.1.RELEASE</version>

</parent>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-data-jpa</artifactId>

</dependency>

<groupId>org.springframework.restdocs</groupId>

<artifactId>spring-restdocs-mockmvc</artifactId>

<version>1.0.1.RELEASE</version>

</dependency>

<groupId>org.hsqldb</groupId>

<artifactId>hsqldb</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter</artifactId>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-logging</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-log4j</artifactId>

</dependency>

</dependencies>

<build>

<artifactId>maven-compiler-plugin</artifactId>

</configuration>

</plugin>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

<mainClass>net.luisalbertogh.springrestdocs.SpringRestDocs</mainClass>

</configuration>

</plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-surefire-plugin</artifactId>

</includes>

</configuration>

</plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<id>generate-docs</id>

<phase>prepare-package</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<sourceDirectory>src/docs/asciidoc</sourceDirectory>

<outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory>

<snippets>${project.build.directory}/generated-snippets</snippets>

</attributes>

</configuration>

</execution>

</executions>

</plugin>

<artifactId>maven-resources-plugin</artifactId>

<id>copy-resources</id>

<phase>prepare-package</phase>

<goals>

<goal>copy-resources</goal>

</goals>

${project.build.outputDirectory}/static/docs/${project.version}

</outputDirectory>

${project.build.directory}/generated-docs/${project.version}

</directory>

</resource>

</resources>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</repository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</repository>

</repositories>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</pluginRepository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</pluginRepository>

</pluginRepositories>

</project>

En este caso, como en otros expuestos en este blog, para facilitar la implementación y ejecución de la prueba, se usa Spring Boot. Para implementar una pequeña aplicacion de prueba que desarrolle una serie de servicios web con acceso a datos, se usa la integración de Spring MVC y Spring Data con Spring Boot, de esta manera podremos implementar una sencilla aplicacion de forma rápida y simple. Se usa HSQLDB como base de datos relacional embebida, que nos permitirá ejecutar las operaciones CRUD clásicas de persistencia de datos.

El resto del pom incluye, además, los plugin que se usarán para, desde Maven, ejecutar los tests y la generación de la documentación (con Asciidoctor).

1. Desarrollar la aplicación de prueba que implementa los servicios web

Vamos a desarrollar una aplicación muy sencilla que nos permita realizar las clásicas operaciones CRUD sobre una entidad concreta y poder acceder a esas operaciones mediante servicios web tipo REST. Nuestra aplicación va a realizar lo siguiente:

Insertar o actualizar un superheroe
Borrar un superheroe
Mostrar un superheroe
Mostrar la lista de superheroes

Para ello desarrollamos una aplicación por capas más o menos clásica que implemente los diferentes niveles de acceso a los datos:

Un POJO que representa la entidad “Superheroe”
Un DAO que por simplicidad solo implementará las operaciones CRUD anteriores
Un Controlador que implementará los servicios web

En este caso, como no hay lógica de negocio, y por simplicidad y porque el post está centrado en la generación de la documentación de los servicios web y no en el desarrollo de la aplicación en sí, nos saltaremos la capa de negocio o de servicios que debería tener este tipo de aplicaciones por capas.

2. POJO y DAO

El POJO representa la entidad que usaremos para la prueba, que como se ha mencionado antes, modela los datos de un superheroe cualquiera, con sus superpoderes, debilidades y demás características. Además de usarlo para la capa de persistencia, también usaremos la misma clase como DTO para transferir datos entre capas de negocio.

/**
 * @author lagarcia
 *
 */
@Entity
public final class Superhero {
    /** The name */
    @NotNull
    private String name;

    /** The super power */
    @NotNull
    private String power;

    /** The evil actitude */
    @NotNull
    private Boolean evil;

    /** The creation date and time */
    private LocalDateTime createdDate;

    /** The creator name */
    private String creator;

    /** The superhero weakness */
    @NotNull
    private String weakness;

    /**
     * Default constructor.
     */
    public Superhero() {
        /* Empty */
    }

    /**
     * Constructor with args.
     *
     * @param nameArg
     * @param powerArg
     * @param evilArg
     */
    public Superhero(String nameArg, String powerArg, Boolean evilArg) {
        name = nameArg;
        power = powerArg;
        evil = evilArg;
    }

    /**
     * @return the name
     */
    @Id
    public String getName() {
        return name;
    }

    /**
     * @param nameArg
     *            the name to set
     */
    public void setName(String nameArg) {
        name = nameArg;
    }

    /**
     * @return the power
     */
    public String getPower() {
        return power;
    }

    /**
     * @param powerArg
     *            the power to set
     */
    public void setPower(String powerArg) {
        power = powerArg;
    }

    /**
     * @return the isEvil
     */
    public Boolean isEvil() {
        return evil;
    }

    /**
     * @param evilArg
     *            the isEvil to set
     */
    public void setEvil(Boolean evilArg) {
        evil = evilArg;
    }

    /**
     * @return the createdDate
     */
    @CreatedDate
    public LocalDateTime getCreatedDate() {
        return createdDate;
    }

    /**
     * @param createdDateArg
     *            the createdDate to set
     */
    public void setCreatedDate(LocalDateTime createdDateArg) {
        createdDate = createdDateArg;
    }

    /**
     * @return the creator
     */
    @CreatedBy
    public String getCreator() {
        return creator;
    }

    /**
     * @param creatorArg
     *            the creator to set
     */
    public void setCreator(String creatorArg) {
        creator = creatorArg;
    }

    /**
     * @return the weakness
     */
    public String getWeakness() {
        return weakness;
    }

    /**
     * @param weaknessArg
     *            the weakness to set
     */
    public void setWeakness(String weaknessArg) {
        weakness = weaknessArg;
    }

    @Override
    public String toString() {
        /* Evil */
        String evilStr = "good";
        if (evil) {
            evilStr = "evil";
        }

        /* Creation date */
        String dateStr = "";
        if (createdDate != null) {
            dateStr = createdDate.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
        }

        return "[" + dateStr + "][" + creator + "] My name is <b>" + name
                + "</b> and my super power is <b>" + power
                + "</b>. Do not panic, I am " + evilStr + ". I am afraid to "
                + weakness;
    }
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

/**

* @author lagarcia

@Entity

public final class Superhero {

/** The name */

@NotNull

private String name;

/** The super power */

@NotNull

private String power;

/** The evil actitude */

@NotNull

private Boolean evil;

/** The creation date and time */

private LocalDateTime createdDate;

/** The creator name */

private String creator;

/** The superhero weakness */

@NotNull

private String weakness;

/**

* Default constructor.

public Superhero() {

/* Empty */

}

/**

* Constructor with args.

* @param nameArg

* @param powerArg

* @param evilArg

public Superhero(String nameArg, String powerArg, Boolean evilArg) {

name = nameArg;

power = powerArg;

evil = evilArg;

}

/**

* @return the name

@Id

public String getName() {

return name;

}

/**

* @param nameArg

* the name to set

public void setName(String nameArg) {

name = nameArg;

}

/**

* @return the power

public String getPower() {

return power;

}

/**

* @param powerArg

* the power to set

public void setPower(String powerArg) {

power = powerArg;

}

/**

* @return the isEvil

public Boolean isEvil() {

return evil;

}

/**

* @param evilArg

* the isEvil to set

public void setEvil(Boolean evilArg) {

evil = evilArg;

}

/**

* @return the createdDate

@CreatedDate

public LocalDateTime getCreatedDate() {

return createdDate;

}

/**

* @param createdDateArg

* the createdDate to set

public void setCreatedDate(LocalDateTime createdDateArg) {

createdDate = createdDateArg;

}

/**

* @return the creator

@CreatedBy

public String getCreator() {

return creator;

}

/**

* @param creatorArg

* the creator to set

public void setCreator(String creatorArg) {

creator = creatorArg;

}

/**

* @return the weakness

public String getWeakness() {

return weakness;

}

/**

* @param weaknessArg

* the weakness to set

public void setWeakness(String weaknessArg) {

weakness = weaknessArg;

}

@Override

public String toString() {

/* Evil */

String evilStr = "good";

if (evil) {

evilStr = "evil";

}

/* Creation date */

String dateStr = "";

if (createdDate != null) {

dateStr = createdDate.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);

}

return "[" + dateStr + "][" + creator + "] My name is " + name

+ " and my super power is " + power

+ ". Do not panic, I am " + evilStr + ". I am afraid to "

+ weakness;

}

El DAO, por motivos de simplicidad, es una interfaz que se exitende del CrudRepository de Spring Data. De esta manera se implementan automaticamente las operaciones CRUD clásicas necesarias para nuestro ejemplo. Usaremos el nombre del superheroe como clave primaria de la entidad.

/**
 * @author lagarcia
 *
 */
public interface SuperheroDAO extends CrudRepository<Superhero, String> {
}

/**

* @author lagarcia

public interface SuperheroDAO extends CrudRepository<Superhero, String> {

}

3. Servicios web

Para implementar los servicios web en este caso usamos Spring MVC. Vamos a seguir en la medida de lo posible las recomendaciones y buenas prácticas en la implementación de servicios de este tipo. Estas recomendaciones afectan a varias características de los servicios, a saber:

URL del servicio
Método HTTP
Códigos HTTP de respuesta

A parte de esto, en nuestro caso, como vamos a invocar los servicios desde una página web, usaremos JSON para enviar y recibir los datos desde los mismos (se podría usar XML en su lugar).

Los servicios que vamos a implementar y sus características son los siguientes:

Inserta o modifica un superheroe

/**
     * Add a new superhero.
     *
     * @param sh
     *            - The new superhero
     * @return The response entity
     */
    @RequestMapping(value = "/superhero", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Void> saveSuperhero(@RequestBody Superhero sh) {
        logger.info("Save a superhero");
        if (sh != null) {
            sh.setCreator("ADMIN");
            sh.setCreatedDate(LocalDateTime.now());
            this.getHeroDAO().save(sh);
            return new ResponseEntity<Void>(HttpStatus.CREATED);
        }

        return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);
    }

/**

* Add a new superhero.

* @param sh

* - The new superhero

* @return The response entity

@RequestMapping(value = "/superhero", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<Void> saveSuperhero(@RequestBody Superhero sh) {

logger.info("Save a superhero");

if (sh != null) {

sh.setCreator("ADMIN");

sh.setCreatedDate(LocalDateTime.now());

this.getHeroDAO().save(sh);

return new ResponseEntity<Void>(HttpStatus.CREATED);

}

return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);

}

Inserta un nuevo superheroe, si éste no existe, o lo modifica con los datos enviados, si existe en función de su clave primaria (nombre).

Obtiene los datos de un superheroe concreto en función de su nombre

/**
     * Get a superhero.
     *
     * @param name
     *            - Superhero name
     *
     * @return A superhero PO
     */
    @RequestMapping(value = "/superhero/{name}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Superhero> getSuperhero(
            @PathVariable("name") String name) {
        logger.info("Get " + name + " superhero");
        Superhero sh = this.getHeroDAO().findOne(name);
        if (sh != null) {
            return new ResponseEntity<Superhero>(sh, HttpStatus.FOUND);
        }

        return new ResponseEntity<Superhero>(HttpStatus.NOT_FOUND);
    }

/**

* Get a superhero.

* @param name

* - Superhero name

* @return A superhero PO

@RequestMapping(value = "/superhero/{name}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<Superhero> getSuperhero(

@PathVariable("name") String name) {

logger.info("Get " + name + " superhero");

Superhero sh = this.getHeroDAO().findOne(name);

if (sh != null) {

return new ResponseEntity<Superhero>(sh, HttpStatus.FOUND);

}

return new ResponseEntity<Superhero>(HttpStatus.NOT_FOUND);

}

Borra un superheroe en función de su nombre

/**
     * Delete a superhero.
     *
     * @param name
     *            - Superhero name
     * @return The response entity
     * */
    @RequestMapping(value = "/superhero/{name}/delete", method = RequestMethod.DELETE)
    public ResponseEntity<Void> deleteSuperhero(
            @PathVariable("name") String name) {
        logger.info("Delete a superhero");
        if (name != null) {
            this.getHeroDAO().delete(name);
            return new ResponseEntity<Void>(HttpStatus.OK);
        }

        return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);
    }

/**

* Delete a superhero.

* @param name

* - Superhero name

* @return The response entity

* */

@RequestMapping(value = "/superhero/{name}/delete", method = RequestMethod.DELETE)

public ResponseEntity<Void> deleteSuperhero(

@PathVariable("name") String name) {

logger.info("Delete a superhero");

if (name != null) {

this.getHeroDAO().delete(name);

return new ResponseEntity<Void>(HttpStatus.OK);

}

return new ResponseEntity<Void>(HttpStatus.BAD_REQUEST);

}

Muestra la lista completa de superheroes

/**
     * Find all superheros.
     *
     * @return The superheros list.
     */
    @RequestMapping(value = "/superhero/find", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<List<Superhero>> findSuperhero() {
        List<Superhero> shList = (List<Superhero>) this.getHeroDAO().findAll();
        if (shList != null && !shList.isEmpty()) {
            return new ResponseEntity<List<Superhero>>(shList, HttpStatus.FOUND);
        }

        return new ResponseEntity<List<Superhero>>(HttpStatus.NOT_FOUND);
    }

/**

* Find all superheros.

* @return The superheros list.

@RequestMapping(value = "/superhero/find", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<List<Superhero>> findSuperhero() {

List<Superhero> shList = (List<Superhero>) this.getHeroDAO().findAll();

if (shList != null && !shList.isEmpty()) {

return new ResponseEntity<List<Superhero>>(shList, HttpStatus.FOUND);

}

return new ResponseEntity<List<Superhero>>(HttpStatus.NOT_FOUND);

}

4. Tests de servicios y generación de documentación

El último paso es implementar los tests de integración de los servicios que además de testear la funcionalidad completa de los mismos, nos permitirá generar la documentación asociada según los criterios que indiquemos en dicha implementación.

Para testear los servicios web usamos MockMVC de Spring, que implementa un cliente HTTP que nos permite invocar dichos servicios y validar los códigos de respuesta HTTP recibidos así como el contenido de la respuesta.

/* Test & document - insert or update service */
            this.mockMvc.perform(
                    post("/superhero").contentType(MediaType.APPLICATION_JSON)
                    .content(this.objectMapper.writeValueAsString(sh)))
                    .andExpect(status().isCreated());

...

/* Test & document - get a superhero service */
            this.mockMvc.perform(
                    get("/superhero/Spiderman").accept(
                            MediaType.APPLICATION_JSON)).andExpect(
                    status().isFound());

/* Test & document - insert or update service */

this.mockMvc.perform(

post("/superhero").contentType(MediaType.APPLICATION_JSON)

.content(this.objectMapper.writeValueAsString(sh)))

.andExpect(status().isCreated());

...

/* Test & document - get a superhero service */

this.mockMvc.perform(

get("/superhero/Spiderman").accept(

MediaType.APPLICATION_JSON)).andExpect(

status().isFound());

Al mismo tiempo inicializamos la generación de la documentación usando la API de Spring REST Docs y especificamos los campos obligatorios de entrada de datos o los campos de los datos de retorno para los servicios relacionados.

/** REST docs configuration */
    @Rule
    public final RestDocumentation restDocumentation = new RestDocumentation(
            "target/generated-snippets");

    /** REST document handler */
    private RestDocumentationResultHandler document;

....

/* Document constraints and request fields */
            ConstrainedFields fields = new ConstrainedFields(Superhero.class);

            this.document
                    .snippets(requestFields(
                            fields.withPath("name").description(
                                    "The superhero name"),
                            fields.withPath("power").description(
                                    "The superhero power"),
                            fields.withPath("creator").description(
                                    "The creator name"),
                            fields.withPath("createdDate").description(
                                    "The creation date"),
                            fields.withPath("evil").description(
                                    "Is the superhero evil?"),
                            fields.withPath("weakness").description(
                                    "The superhero weakness")));

/** REST docs configuration */

@Rule

public final RestDocumentation restDocumentation = new RestDocumentation(

"target/generated-snippets");

/** REST document handler */

private RestDocumentationResultHandler document;

....

/* Document constraints and request fields */

ConstrainedFields fields = new ConstrainedFields(Superhero.class);

this.document

.snippets(requestFields(

fields.withPath("name").description(

"The superhero name"),

fields.withPath("power").description(

"The superhero power"),

fields.withPath("creator").description(

"The creator name"),

fields.withPath("createdDate").description(

"The creation date"),

fields.withPath("evil").description(

"Is the superhero evil?"),

fields.withPath("weakness").description(

"The superhero weakness")));

5. Asciidoctor

Definimos en un fichero de texto plano el contenido y el formato de la página HTML que se generará como índice de nuestra documentación. Para ello usamos la sintaxis de Asciidoctor. Además seguimos recomendaciones de buenas prácticas relacionadas con la redacción de este tipo de documentación, a saber:

Indicar en un apartado diferente los distintos tipos de códigos de respuesta HTTP y su significado
Indicar en un apartado diferente los tipos de métodos HTTP usados y su significado
Indicar el tipo de respuesta recibida cuando se generar un error
Para cada servicio web documentado, indicar un ejemplo de invocación de la URL usando curl, ejemplos de petición y respuesta HTTP y si fuera necesario, el significado de los campos de entrada y salida de los datos usados. Esta información es la que genera de forma automática Spring REST Docs en cualquier caso, salvo la descripción de los campos de entrada y/o salida, que tendríamos que especificar en cada test si queremos que se genere

= Spring REST Docs API
luisalbertogh <luisalbertogh@hotmail.com>
:doctype: book
:toc:
:sectanchors:
:sectlinks:
:toclevels: 4
:source-highlighter: highlightjs

[[overview]]
= Overview

[[overview-http-verbs]]
== HTTP verbs

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP verbs.

|===
| Verb | Usage

| `GET`
| Used to retrieve a resource

| `POST`
| Used to create (add or update) a new resource

| `DELETE`
| Used to delete an existing resource
|===

[[overview-http-status-codes]]
== HTTP status codes

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its
use of HTTP status codes.

|===
| Status code | Usage

| `200 OK`
| The request completed successfully

| `201 Created`
| A new resource has been saved (created or updated) successfully.
// The resource's URI is available from the response's `Location` header

| `302 Found`
| The searched resource was successfully found

| `400 Bad Request`
| The request was malformed. The response body will include an error providing further information

| `404 Not Found`
| The requested resource did not exist
|===

[[overview-errors]]
== Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object
that describes the problem. The error object has the following structure:

For example, a request that attempts to save a malformed superhero will produce a
`400 Bad Request` response:

[[overview-hypermedia]]
== Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their
responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application
Language (HAL)] format. Links can be found benath the `_links` key. Users of the API should
not created URIs themselves, instead they should use the above-described links to navigate
from resource to resource.

[[resources]]
= Resources

[[resources-save-superhero]]
== Save (add or update) a superhero

=== Example
include::{snippets}/test-save-superhero/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-save-superhero/http-request.adoc[]

=== HTTP response
include::{snippets}/test-save-superhero/http-response.adoc[]

=== Request fields
include::{snippets}/test-save-superhero/request-fields.adoc[]

[[resources-get-superhero]]
== Get a superhero

=== Example
include::{snippets}/test-get-superhero/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-get-superhero/http-request.adoc[]

=== HTTP response
include::{snippets}/test-get-superhero/http-response.adoc[]

=== Response fields
include::{snippets}/test-get-superhero/response-fields.adoc[]

[[resources-find-superheros]]
== Find superheros

=== Example
include::{snippets}/test-find-superheros/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-find-superheros/http-request.adoc[]

=== HTTP response
include::{snippets}/test-find-superheros/http-response.adoc[]

[[resources-delete-superhero]]
== Delete a superhero

=== Example
include::{snippets}/test-delete-superhero/curl-request.adoc[]

=== HTTP request
include::{snippets}/test-delete-superhero/http-request.adoc[]

=== HTTP response
include::{snippets}/test-delete-superhero/http-response.adoc[]

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

= Spring REST Docs API

luisalbertogh <luisalbertogh@hotmail.com>

:doctype: book

:toc:

:sectanchors:

:sectlinks:

:toclevels: 4

:source-highlighter: highlightjs

[[overview]]

= Overview

[[overview-http-verbs]]

== HTTP verbs

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its

use of HTTP verbs.

|===

| Verb | Usage

| `GET`

| Used to retrieve a resource

| `POST`

| Used to create (add or update) a new resource

| `DELETE`

| Used to delete an existing resource

|===

[[overview-http-status-codes]]

== HTTP status codes

RESTful SpringRestDocs tries to adhere as closely as possible to standard HTTP and REST conventions in its

use of HTTP status codes.

|===

| Status code | Usage

| `200 OK`

| The request completed successfully

| `201 Created`

| A new resource has been saved (created or updated) successfully.

// The resource's URI is available from the response's `Location` header

| `302 Found`

| The searched resource was successfully found

| `400 Bad Request`

| The request was malformed. The response body will include an error providing further information

| `404 Not Found`

| The requested resource did not exist

|===

[[overview-errors]]

== Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object

that describes the problem. The error object has the following structure:

For example, a request that attempts to save a malformed superhero will produce a

`400 Bad Request` response:

[[overview-hypermedia]]

== Hypermedia

RESTful Notes uses hypermedia and resources include links to other resources in their

responses. Responses are in http://stateless.co/hal_specification.html[Hypertext Application

Language (HAL)] format. Links can be found benath the `_links` key. Users of the API should

not created URIs themselves, instead they should use the above-described links to navigate

from resource to resource.

[[resources]]

= Resources

[[resources-save-superhero]]

== Save (add or update) a superhero

=== Example

include::{snippets}/test-save-superhero/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-save-superhero/http-request.adoc[]

=== HTTP response

include::{snippets}/test-save-superhero/http-response.adoc[]

=== Request fields

include::{snippets}/test-save-superhero/request-fields.adoc[]

[[resources-get-superhero]]

== Get a superhero

=== Example

include::{snippets}/test-get-superhero/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-get-superhero/http-request.adoc[]

=== HTTP response

include::{snippets}/test-get-superhero/http-response.adoc[]

=== Response fields

include::{snippets}/test-get-superhero/response-fields.adoc[]

[[resources-find-superheros]]

== Find superheros

=== Example

include::{snippets}/test-find-superheros/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-find-superheros/http-request.adoc[]

=== HTTP response

include::{snippets}/test-find-superheros/http-response.adoc[]

[[resources-delete-superhero]]

== Delete a superhero

=== Example

include::{snippets}/test-delete-superhero/curl-request.adoc[]

=== HTTP request

include::{snippets}/test-delete-superhero/http-request.adoc[]

=== HTTP response

include::{snippets}/test-delete-superhero/http-response.adoc[]

La ruta al fichero se incluye en el plugin de Asciidoctor para Maven, en el pom.xml.

<!-- Asciidoctor plugin - Plugin for REST documentation -->
      <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.2</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <!-- Configured to include documentation within the executable JAR file -->
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <strong><sourceDirectory>src/docs/asciidoc</sourceDirectory></strong>
                        <strong><outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory></strong>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <attributes>
                            <snippets>${project.build.directory}/generated-snippets</snippets>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<id>generate-docs</id>

<phase>prepare-package</phase>

<goals>

<goal>process-asciidoc</goal>

</goals>

<sourceDirectory>src/docs/asciidoc</sourceDirectory>

<outputDirectory>${project.build.directory}/generated-docs/${project.version}</outputDirectory>

<snippets>${project.build.directory}/generated-snippets</snippets>

</attributes>

</configuration>

</execution>

</executions>

</plugin>

6. Ejecución de tests y generación de documentación

Configuramos los plugin de Maven en el pom.xml para que se ejecute la generación de la documentación al generar un nuevo “release” de la aplicación, es decir, cuando se invoque el goal “package” de Maven. Previamente se ejecutarán los tests de forma automática. Si falla el test o la generación de la documentación para un servicio dado, se indicará en la salida por consola y no se generará ni el release ni la documentación de ninguno de los servicios.

Maven goals

7. Visualización de la documentación generada

La documentación se genera en la ruta indicada en el plugin de Maven (ver arriba). Por un lado se generan los “snippets” que es la documentación que corresponde a cada servicio, y por otro una página principal o índice HTML que enlaza a esso “snippets” según hayamos indicado en el fichero de texto plano que define la página y que se describe en el punto 5.

Índice generado

Descripción de los servicios web

Spring AOP y AspectJ en tres patadas

Inauguramos el nuevo nombre y aspecto del blog, que pasa de “Posteando mientras…” a “El Recetario”, con una nueva receta de Spring. En este caso vamos a cocinar algo con Spring AOP.

Qué cocinamos

Spring AOP es la parte de Spring relacionada con la porgramación orientada a aspectos. La programación orientada a aspectos es un paradigma informático que se fundamenta en programar en función de un aspecto, funcionalidad o característica concreta, en lugar de hacerlo centrado en un servicio o método específico. Es decir, que se puede codificar una funcionalidad o actividad no en función de un método o servicio específico, si no para un conjunto de ellos que representan una característica o aspecto representativo de la aplicación.

Por ejemplo, se puede programar la escritura de logs, la intercepción de excepciones, la generación de comentarios o auditorías en función de la ejecución o resultados de varios métodos que implementan una única funcionalidad o característica de la aplicación final. Así, podemos crear una entrada en un log cada vez que se invoque un método de la capa de servicios, o cada vez que se llame a un método de un paquete concreto.

Las acciones a realizar o implementación del aspecto es el “Advice”. Un aspecto puede tener varios “advices”, y cada “advice” estara asociado a un punto de interés o “pointcut”. El punto de interés que se usa para indicar cuando ha de ejecutarse el “advice”, es decir, los métodos que se quiere controlar.

AspectJ facilita la creación de los aspectos usando anotaciones.

Ingredientes

Spring Boot
Spring MVC
Spring AOP
AspectJ
Log4j
Maven

Paso a paso

1. Pom.xml

Configuramos el pom.xml de Spring Boot para que resuelva las dependencias necesarias para crear una aplicación con Spring AOP. La aplicación va a ser una simple API REST que recibirá una petición para contar cuantas veces aparece una determinada letra en una palabra, de ahi que necesitemos Spring MVC para la parte web. Se va a capturar la invocación y resultados de la ejecución de esta API usando aspectos y se escribirá en un log cuando esto ocurrá usando Log4j.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>SpringAOP</groupId>
  <artifactId>SpringAOP</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>1.3.0.BUILD-SNAPSHOT</version>
  </parent>

  <dependencies>
      <!-- Import dependency management from Spring Boot -->
      <!-- <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-dependencies</artifactId>
          <version>1.3.0.BUILD-SNAPSHOT</version>
          <type>pom</type>
          <scope>import</scope>
      </dependency> -->

      <!-- Add typical dependencies for a web application -->
      <dependency>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

      <!-- Use Log4j instead of default logging -->
          <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-logging</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-log4j</artifactId>
        </dependency>

        <!-- Spring AOP -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>
  </dependencies>

  <build>
    <sourceDirectory>src</sourceDirectory>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>

      <!-- Package as an executable jar -->
      <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

  <!-- Add Spring repositories -->
  <!-- (you don't need this if you are using a .RELEASE version) -->
  <repositories>
      <repository>
          <id>spring-snapshots</id>
          <url>http://repo.spring.io/snapshot</url>
          <snapshots><enabled>true</enabled></snapshots>
      </repository>
      <repository>
          <id>spring-milestones</id>
          <url>http://repo.spring.io/milestone</url>
      </repository>
  </repositories>
  <pluginRepositories>
      <pluginRepository>
          <id>spring-snapshots</id>
          <url>http://repo.spring.io/snapshot</url>
      </pluginRepository>
      <pluginRepository>
          <id>spring-milestones</id>
          <url>http://repo.spring.io/milestone</url>
      </pluginRepository>
  </pluginRepositories>
</project>

<groupId>SpringAOP</groupId>

<artifactId>SpringAOP</artifactId>

<version>0.0.1-SNAPSHOT</version>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-parent</artifactId>

<version>1.3.0.BUILD-SNAPSHOT</version>

</parent>

<!-- <dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-dependencies</artifactId>

<version>1.3.0.BUILD-SNAPSHOT</version>

<scope>import</scope>

</dependency> -->

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter</artifactId>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-logging</artifactId>

</exclusion>

</exclusions>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-log4j</artifactId>

</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-aop</artifactId>

</dependency>

</dependencies>

<build>

<artifactId>maven-compiler-plugin</artifactId>

</configuration>

</plugin>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

</plugins>

</build>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</repository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</repository>

</repositories>

<id>spring-snapshots</id>

<url>http://repo.spring.io/snapshot</url>

</pluginRepository>

<id>spring-milestones</id>

<url>http://repo.spring.io/milestone</url>

</pluginRepository>

</pluginRepositories>

</project>

2. Inicializar Spring Boot

Se puede obtener más información acerca de Spring Boot en este otro post. Basta con incluir el siguiente código para inicializar la aplicación como Spring Boot. Esto hará que se ejecute en el Tomcat embebido que se carga automaticamente al incluir las dependencias de Spring MVC.

/**
 * Main class.
 * @author lagarcia
 *
 */
@SpringBootApplication
public class SpringAOP {

    /**
     * Main method.
     * @param args
     */
    public static void main(String[] args) {
        SpringApplication.run(SpringAOP.class, args);
    }

}

/**

* Main class.

* @author lagarcia

@SpringBootApplication

public class SpringAOP {

/**

* Main method.

* @param args

public static void main(String[] args) {

SpringApplication.run(SpringAOP.class, args);

}

3. Crear el servicio que servirá de pointcut para los advices del aspecto

Como ejemplo práctico disponemos de un servicio que recibe una palabra y una letra. Éste cuenta cuantas veces aparece la letra en dicha palabra y devuelve la cuenta.

/**
 * @author lagarcia
 *
 */
@Service
public class SpringAOPService {
    /**
     * Count the number of 'c' appearances in the passed word.
     *
     * @param word
     *            - The word
     * @param c
     *            - The char to count
     * @return The number of times the c char is in the word
     */
    public Integer countCharsService(String word, char c) {
        int count = 0;
        char[] chars = word.toCharArray();
        for (char ch : chars) {
            if (ch == c) {
                count++;
            }
        }

        return new Integer(count);
    }
}

/**

* @author lagarcia

@Service

public class SpringAOPService {

/**

* Count the number of 'c' appearances in the passed word.

* @param word

* - The word

* @param c

* - The char to count

* @return The number of times the c char is in the word

public Integer countCharsService(String word, char c) {

int count = 0;

char[] chars = word.toCharArray();

for (char ch : chars) {

if (ch == c) {

count++;

}

return new Integer(count);

}

4. Controlador REST

Como se ha mencionado antes, se va ha implementar un servicio web tipo REST que se invocará desde un navegador web. Este servicio recibe en su URL una palabra y una letra, que seran los datos que se le pasarán al servicio antes creado.

/**
 * Example controller class.
 *
 * @author lagarcia
 *
 */
@RestController
public class ExampleController {

    /** A logger reference */
    private static Logger logger = Logger.getLogger(ExampleController.class);

    /** A Spring service */
    @Autowired
    private SpringAOPService aService;

    /**
     * Go to home.
     *
     * @return
     */
    @RequestMapping("/home")
    String home() {
        logger.info("Entering in HOME");
        return "Hola Spring AOP";
    }

    /**
     * Perform a calculation.
     *
     * @return
     */
    @RequestMapping("/calculate/{word}/{c}")
    String calculate(@PathVariable String word, @PathVariable String c) {
        logger.info("Entering in CALCULATE");
        int count = 0;
        try {
            count = this.getaService().countCharsService(word, c.charAt(0));
        } catch (Exception ex) {
            ex.printStackTrace();
        }

        logger.info("Finishing CALCULATE");

        return "¿Cuántas " + c + "es hay en la palabra " + word + " ? Hay "
        + count;
    }

    /**
     * @return the aService
     */
    public SpringAOPService getaService() {
        return aService;
    }

    /**
     * @param aServiceArg
     *            the aService to set
     */
    public void setaService(SpringAOPService aServiceArg) {
        aService = aServiceArg;
    }
}

/**

* Example controller class.

* @author lagarcia

@RestController

public class ExampleController {

/** A logger reference */

private static Logger logger = Logger.getLogger(ExampleController.class);

/** A Spring service */

@Autowired

private SpringAOPService aService;

/**

* Go to home.

* @return

@RequestMapping("/home")

String home() {

logger.info("Entering in HOME");

return "Hola Spring AOP";

}

/**

* Perform a calculation.

* @return

@RequestMapping("/calculate/{word}/{c}")

String calculate(@PathVariable String word, @PathVariable String c) {

logger.info("Entering in CALCULATE");

int count = 0;

try {

count = this.getaService().countCharsService(word, c.charAt(0));

} catch (Exception ex) {

ex.printStackTrace();

}

logger.info("Finishing CALCULATE");

return "¿Cuántas " + c + "es hay en la palabra " + word + " ? Hay "

+ count;

}

/**

* @return the aService

public SpringAOPService getaService() {

return aService;

}

/**

* @param aServiceArg

* the aService to set

public void setaService(SpringAOPService aServiceArg) {

aService = aServiceArg;

}

5. Aspecto

Por último lo interesante de esta receta. La creación del aspecto usando las anotaciones de AspectJ. El aspecto puede tener varios “advices”, a saber:

@Before – Para antes de la ejecución del pointcut
@After – Para después de la ejecución del pointcut
@AfterReturning – Para después de la ejecución y recibiendo lo que se retorna
@AfterThrowing – Para después de que se lanza una excepción
@Around – Para antes y después del pointcut

Declaramos la clase como Aspect y como Component para que Spring la instancie automaticamente y la configure como aspecto:

/**
 * @author lagarcia
 *
 */
@Aspect
@Component
public class LogAspect {
...
}

/**

* @author lagarcia

@Aspect

@Component

public class LogAspect {

...

}

Implementamos a modo de ejemplo los sigueintes advices:

- logBefore, para que escriba un mensaje en el log antes de ejecutar el servicio anterior:

/**
     * Log before method is executed.
     *
     * @param joinPoint
     */
    @Before("execution(* net.luisalbertogh.springaop..*Service*(..))")
    public void logBefore(JoinPoint joinPoint) {
        logger.info("logBefore");
        logger.info("Log before in: " + joinPoint.getSignature().getName());
    }

/**

* Log before method is executed.

* @param joinPoint

@Before("execution(* net.luisalbertogh.springaop..*Service*(..))")

public void logBefore(JoinPoint joinPoint) {

logger.info("logBefore");

logger.info("Log before in: " + joinPoint.getSignature().getName());

}

Usamos la anotación @Before y el pointcut será la ejecución de cualquier método que tenga el texto Service en su nombre dentro del paquete net.luisalbertogh.springaop, independientemente de lo que reciban como argumento.

- logAfterReturning, para que escriba en el log después de la ejecución del servicio, e imprima el resultado obtenido:

/**
     * Log after method is executed and get returned value.
     *
     * @param joinPoint
     * @param result
     */
    @AfterReturning(pointcut = "execution(* net.luisalbertogh.springaop..*Service*(..))", returning = "result")
    public void logAfterReturning(JoinPoint joinPoint, Object result) {
        logger.info("logAfterReturning");
        logger.info("Log after in: " + joinPoint.getSignature().getName());
        logger.info("- And value returned is: " + result);
    }

/**

* Log after method is executed and get returned value.

* @param joinPoint

* @param result

@AfterReturning(pointcut = "execution(* net.luisalbertogh.springaop..*Service*(..))", returning = "result")

public void logAfterReturning(JoinPoint joinPoint, Object result) {

logger.info("logAfterReturning");

logger.info("Log after in: " + joinPoint.getSignature().getName());

logger.info("- And value returned is: " + result);

}

Al igual que en el caso anterior, se usa la anotación y se define el pointcut correspondiente, pero en este caso además se añade el resultado (result).

- logAfterThrowing, para que escriba después de lanzar una excepción e indique el mensaje de error en el log:

/**
     * Log after exception is thrown.
     *
     * @param joinPoint
     * @param exception
     */
    @AfterThrowing(pointcut = "execution(* net.luisalbertogh.springaop..*Service*(..))", throwing = "exception")
    public void logAfterThrowing(JoinPoint joinPoint, Throwable exception) {
        logger.info("logAfterThrowing");
        logger.info("Log in: " + joinPoint.getSignature().getName());
        logger.info("- And thrown exception is: " + exception.getMessage());
    }

/**

* Log after exception is thrown.

* @param joinPoint

* @param exception

@AfterThrowing(pointcut = "execution(* net.luisalbertogh.springaop..*Service*(..))", throwing = "exception")

public void logAfterThrowing(JoinPoint joinPoint, Throwable exception) {

logger.info("logAfterThrowing");

logger.info("Log in: " + joinPoint.getSignature().getName());

logger.info("- And thrown exception is: " + exception.getMessage());

}

- logAround, para que escriba en el log antes y después de la ejecución del servicio. En este caso, lo que ocurre es que se pasa la ejecución del pointcut al advice. Entonces para que continue la ejecución del servicio se usa joinPoint.proceed().

/**
     * Log around the method invocation.
     *
     * @param joinPoint
     * @throws Throwable
     */
    @Around("execution(* net.luisalbertogh.springaop..*Service*(..))")
    public void logAround(ProceedingJoinPoint joinPoint) throws Throwable {
        logger.info("logAround");
        logger.info("Log before in: " + joinPoint.getSignature().getName());
        /* Back to invoked method */
        joinPoint.proceed();
        logger.info("Log after in: " + joinPoint.getSignature().getName());
    }

/**

* Log around the method invocation.

* @param joinPoint

* @throws Throwable

@Around("execution(* net.luisalbertogh.springaop..*Service*(..))")

public void logAround(ProceedingJoinPoint joinPoint) throws Throwable {

logger.info("logAround");

logger.info("Log before in: " + joinPoint.getSignature().getName());

/* Back to invoked method */

joinPoint.proceed();

logger.info("Log after in: " + joinPoint.getSignature().getName());

}

El resultado

En el navegador se vería esto:

Spring AOP

Y en el log o en la consola:

INFO : net.luisalbertogh.springaop.controllers.ExampleController – Entering in CALCULATE
INFO : net.luisalbertogh.springaop.aspect.LogAspect – logBefore
INFO : net.luisalbertogh.springaop.aspect.LogAspect – Log before in: countCharsService
INFO : net.luisalbertogh.springaop.aspect.LogAspect – logAfterReturning
INFO : net.luisalbertogh.springaop.aspect.LogAspect – Log after in: countCharsService
INFO : net.luisalbertogh.springaop.aspect.LogAspect – - And value returned is: 4
INFO : net.luisalbertogh.springaop.controllers.ExampleController – Finishing CALCULATE

El proyecto completo aqui. Y también en Github.

Breve ejemplo con Spring Batch

Este post muestra un ejemplo simple de uso de Spring Batch. Spring Batch es un componente más de la suite de Spring que en este caso nos permite implementar procesamientos batch de forma rápida y sencilla.

Llamaremos procesamiento batch al mecanismo que nos permite ejecutar un conjunto de operaciones similares pero de contenido diferente por lotes, es decir, como un todo, considerando el conjunto de operaciones como una única operación.

Para ello, Spring Batch hace uso de una metodología común a múltiples implementaciones de ejecuciones batch o por lotes. Esta metodología hace uso de los siguientes conceptos para definir y desarrollar los lotes a ejecutar:

- Job. Es el mecanismo principal de ejecución Sería la tarea encargada de ejecutar el conjunto de lotes programado. Una ventaja del job es que se puede programar para ejecutarse de forma recurrente, aunque este mecanismo no esta diseñado para sustituir a otros mecanismos o tecnologías de ejecución recurrente y programación como Quartz o similar, mucho más potentes y funcionales que el mecanismo por defecto de estos jobs. Un job estaría formado por steps o pasos de ejecución. Cada uno de esos pasos sería un lote. El job definiría el orden de ejecución de esos pasos o lotes.

- Step. Es la representación de un lote. Formaría parte de un job que se encargaria de ejecutarlo, bien en solitario o como parte de una ejecución múltiple de varios lotes diferentes. El step definiría una entrada, en forma de un Reader que leería los datos a procesar, un Processor, que procesaría los datos, es decir, implementaría la transformación del dato en sí, y un Writer que persistiría el procesamiento.

- Readers, processors y writers. Como se indica en el anterior punto, serían parte de cada paso y constituirían el flujo de datos de cada lote. El reader leería los datos uno a uno o por bloques, le pasaría los datos al processor que los transformaría, y estos irían despues al writer que, por bloques, persistiría los cambios. Todo el bloque procesado sería considerado una sola transacción.

- Otros elementos a tener en cuenta serían el lanzador de jobs, el respositorio donde se almacena la configuración y el estado de cada job, etc. pero en este ejemplo nos centraremos en los tres primero elementos antes mencionados.

Spring Batch

En este ejemplo vamos a desarrollar una aplicación enterprise que al arrancar ejecuta automaticamente un job con un solo paso que lee de base de datos tres registros, los modifica, y guarda los cambios. Despues, desde una página web, podemos verificar que se hicieron los cambios, y también desde los ficheros de log.

1. Spring Boot y dependencias Maven

Partimos del ejemplo con Spring Data de este otro post. Añadimos la siguiente dependencia al pom.xml:

<!-- Add typical dependencies for a spring batch -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-batch</artifactId>
</dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-batch</artifactId>

</dependency>

Esta dependencia incluye toda la parafernalia necesaria para usar Spring Batch.

2. Configuración del batch

Configuraremos el batch usando una clase java. Creamos la siguiente clase:

/**
* @author lagarcia
*
*/
@Configuration
@EnableBatchProcessing
public class BatchConfiguration {

/** Entity manager factory */
@Autowired
private EntityManagerFactory emFactory;

/**
* Superhero item reader.
*
* @return The superhero item
*/
@Bean
public ItemReader<Superhero> reader() {
  JpaPagingItemReader<Superhero> ireader = new JpaPagingItemReader<>();
  ireader.setEntityManagerFactory(this.getEmFactory());
  ireader.setQueryString("select entity from Superhero entity order by entity.name desc");
  ireader.setPageSize(5);
  return ireader;
}

/**
* Superhero item processor.
*
* @return The superhero processor
*/
@Bean
public ItemProcessor<Superhero, Superhero> processor() {
  return new SuperheroProcessor();
}

/**
* Superhero item writer.
*
* @param dataSource
*            - The datasource
* @return The superhero item writer
*/
@Bean
public ItemWriter<Superhero> writer(DataSource dataSource) {
  JpaItemWriter<Superhero> iwriter = new JpaItemWriter<>();
  iwriter.setEntityManagerFactory(this.getEmFactory());
  return iwriter;
}

/**
* Spring batch job.
*
* @param jobs
* @param s1
* @param listener
* @return
*/
@Bean
public Job superHeroJob(JobBuilderFactory jobs, Step s1,
JobExecutionListener listener) {
  return jobs.get("superHeroJob").incrementer(new RunIdIncrementer())
   .listener(listener).flow(s1).end().build();
}

/**
* Spring batch superhero job - Step 01
*
* @param stepBuilderFactory
* @param reader
* @param writer
* @param processor
* @return
*/
@Bean
public Step step1(StepBuilderFactory stepBuilderFactory,
  ItemReader<Superhero> reader, ItemWriter<Superhero> writer,
  ItemProcessor<Superhero, Superhero> processor) {
  return stepBuilderFactory.get("step01")
    .<Superhero, Superhero> chunk(10).reader(reader)
    .processor(processor).writer(writer).build();
}

/**
* @return the emFactory
*/
public EntityManagerFactory getEmFactory() {
  return emFactory;
}

/**
* @param emFactoryArg
*            the emFactory to set
*/
public void setEmFactory(EntityManagerFactory emFactoryArg) {
  emFactory = emFactoryArg;
}
}

/**

* @author lagarcia

@Configuration

@EnableBatchProcessing

public class BatchConfiguration {

/** Entity manager factory */

@Autowired

private EntityManagerFactory emFactory;

/**

* Superhero item reader.

* @return The superhero item

@Bean

public ItemReader<Superhero> reader() {

JpaPagingItemReader<Superhero> ireader = new JpaPagingItemReader<>();

ireader.setEntityManagerFactory(this.getEmFactory());

ireader.setQueryString("select entity from Superhero entity order by entity.name desc");

ireader.setPageSize(5);

return ireader;

}

/**

* Superhero item processor.

* @return The superhero processor

@Bean

public ItemProcessor<Superhero, Superhero> processor() {

return new SuperheroProcessor();

}

/**

* Superhero item writer.

* @param dataSource

* - The datasource

* @return The superhero item writer

@Bean

public ItemWriter<Superhero> writer(DataSource dataSource) {

JpaItemWriter<Superhero> iwriter = new JpaItemWriter<>();

iwriter.setEntityManagerFactory(this.getEmFactory());

return iwriter;

}

/**

* Spring batch job.

* @param jobs

* @param s1

* @param listener

* @return

@Bean

public Job superHeroJob(JobBuilderFactory jobs, Step s1,

JobExecutionListener listener) {

return jobs.get("superHeroJob").incrementer(new RunIdIncrementer())

.listener(listener).flow(s1).end().build();

}

/**

* Spring batch superhero job - Step 01

* @param stepBuilderFactory

* @param reader

* @param writer

* @param processor

* @return

@Bean

public Step step1(StepBuilderFactory stepBuilderFactory,

ItemReader<Superhero> reader, ItemWriter<Superhero> writer,

ItemProcessor<Superhero, Superhero> processor) {

return stepBuilderFactory.get("step01")

.<Superhero, Superhero> chunk(10).reader(reader)

.processor(processor).writer(writer).build();

}

/**

* @return the emFactory

public EntityManagerFactory getEmFactory() {

return emFactory;

}

/**

* @param emFactoryArg

* the emFactory to set

public void setEmFactory(EntityManagerFactory emFactoryArg) {

emFactory = emFactoryArg;

}

Esto es todo lo que se necesita para configurar el batch. Vamos paso a paso:

- Usamos @Configuration para indicar que es una clase de configuración. Después añadimos @EnableBatchProcessing para indicar que se configura Spring Batch.

- Enlazamos con el EntityManagerFactory que usaremos para leer y escribir de la base de datos embebida. Spring Boot ha configurado ya por defecto el datasource y lo ha enlazado con el EntityManagerFactory.

/** Entity manager factory */
@Autowired
private EntityManagerFactory emFactory;

/** Entity manager factory */

@Autowired

private EntityManagerFactory emFactory;

- Definimos el job. En este caso el job tiene un solo paso (s1). Usamos el RunIdIncrementer() para asignarle un ID incremental a la ejecución del job, ya que Spring Batch almacena el estado de cada job en base de datos. También se le asocia un listener que estará escuchando a los eventos del job. Hablaremos de él más adelante.

/**
* Spring batch job.
*
* @param jobs
* @param s1
* @param listener
* @return
*/
@Bean
public Job superHeroJob(JobBuilderFactory jobs, Step s1,
JobExecutionListener listener) {
  return jobs.get("superHeroJob").incrementer(new RunIdIncrementer())
    .listener(listener).flow(s1).end().build();
}

/**

* Spring batch job.

* @param jobs

* @param s1

* @param listener

* @return

@Bean

public Job superHeroJob(JobBuilderFactory jobs, Step s1,

JobExecutionListener listener) {

return jobs.get("superHeroJob").incrementer(new RunIdIncrementer())

.listener(listener).flow(s1).end().build();

}

- Definimos el lote, en este caso el paso que se ejecutará dentro del job. Especificamos que se escribirán los datos de diez en diez con el método chunk(). El lote o paso tendra un reader, un processor y un writer, como es habitual.

/**
* Spring batch superhero job - Step 01
*
* @param stepBuilderFactory
* @param reader
* @param writer
* @param processor
* @return
*/
@Bean
public Step step1(StepBuilderFactory stepBuilderFactory,
ItemReader<Superhero> reader, ItemWriter<Superhero> writer,
ItemProcessor<Superhero, Superhero> processor) {
  return stepBuilderFactory.get("step01")
    .<Superhero, Superhero> chunk(10).reader(reader)
    .processor(processor).writer(writer).build();
}

/**

* Spring batch superhero job - Step 01

* @param stepBuilderFactory

* @param reader

* @param writer

* @param processor

* @return

@Bean

public Step step1(StepBuilderFactory stepBuilderFactory,

ItemReader<Superhero> reader, ItemWriter<Superhero> writer,

ItemProcessor<Superhero, Superhero> processor) {

return stepBuilderFactory.get("step01")

.<Superhero, Superhero> chunk(10).reader(reader)

.processor(processor).writer(writer).build();

}

- Definimos el reader. En este caso hacemos uso de un reader para JPA, ya que leemos de una base de datos y tenemos el modelo de datos definido con JPA. Usamos una query en JPQL y especificamos que se pagine lo leido de cinco en cinco elementos (setPageSize), que iran pasando al procesador.

/**
* Superhero item reader.
*
* @return The superhero item
*/
@Bean
public ItemReader<Superhero> reader() {
  JpaPagingItemReader<Superhero> ireader = new JpaPagingItemReader<>();
  ireader.setEntityManagerFactory(this.getEmFactory());
  ireader.setQueryString("select entity from Superhero entity order by entity.name desc");
  ireader.setPageSize(5);
  return ireader;
}

/**

* Superhero item reader.

* @return The superhero item

@Bean

public ItemReader<Superhero> reader() {

JpaPagingItemReader<Superhero> ireader = new JpaPagingItemReader<>();

ireader.setEntityManagerFactory(this.getEmFactory());

ireader.setQueryString("select entity from Superhero entity order by entity.name desc");

ireader.setPageSize(5);

return ireader;

}

- Definimos el processor. Creamos una nueva clase (SuperheroProcessor.java) para ello. El processor recibe un objeto Superhero y devuelve también un Superhero (podría devolver otro tipo de dato). En este caso el procesador modifica un campo del POJO en función de su ID (name).

/**
* Superhero item processor.
*
* @return The superhero processor
*/
@Bean
public ItemProcessor<Superhero, Superhero> processor() {
  return new SuperheroProcessor();
}

/**

* Superhero item processor.

* @return The superhero processor

@Bean

public ItemProcessor<Superhero, Superhero> processor() {

return new SuperheroProcessor();

}

- Definimos el writer. Simplemente escribira de diez en diez en base de datos y hara commit sobre ese bloque de datos.

/**
* Superhero item writer.
*
* @param dataSource
*            - The datasource
* @return The superhero item writer
*/
@Bean
public ItemWriter<Superhero> writer(DataSource dataSource) {
  JpaItemWriter<Superhero> iwriter = new JpaItemWriter<>();
  iwriter.setEntityManagerFactory(this.getEmFactory());
  return iwriter;
}

/**

* Superhero item writer.

* @param dataSource

* - The datasource

* @return The superhero item writer

@Bean

public ItemWriter<Superhero> writer(DataSource dataSource) {

JpaItemWriter<Superhero> iwriter = new JpaItemWriter<>();

iwriter.setEntityManagerFactory(this.getEmFactory());

return iwriter;

}

3. Procesamiento de los datos

La clase que implementa el procesador seria tal que así:

/**
* @author lagarcia
*
*/
public class SuperheroProcessor implements ItemProcessor<Superhero, Superhero> {

/** A logger reference */
private static Logger logger = Logger.getLogger(SuperheroProcessor.class);

/**
* Process superhero.
*/
@Override
public Superhero process(Superhero superheroArg) throws Exception {
  if (superheroArg != null) {
    logger.info("Procesando a " + superheroArg.getName());
    switch (superheroArg.getName()) {
      case "Superman": {
        superheroArg.setWeakness("Kryptonite");
        break;
      }
      case "Flash": {
        superheroArg.setWeakness("Speed of light");
        break;
      }
      case "Dr. Magneto": {
        superheroArg.setWeakness("Plastic");
        break;
      }
    }

    return superheroArg;
  }
  return null;
}
}

/**

* @author lagarcia

public class SuperheroProcessor implements ItemProcessor<Superhero, Superhero> {

/** A logger reference */

private static Logger logger = Logger.getLogger(SuperheroProcessor.class);

/**

* Process superhero.

@Override

public Superhero process(Superhero superheroArg) throws Exception {

if (superheroArg != null) {

logger.info("Procesando a " + superheroArg.getName());

switch (superheroArg.getName()) {

case "Superman": {

superheroArg.setWeakness("Kryptonite");

break;

}

case "Flash": {

superheroArg.setWeakness("Speed of light");

break;

}

case "Dr. Magneto": {

superheroArg.setWeakness("Plastic");

break;

}

return superheroArg;

}

return null;

}

Como se ha mencionado antes, recibe un objeto de tipo Superhero, lo modifica, y devuelve el mismo objeto.

4. Listener del job

Se define un listener para el job que escucha los eventos del mismo. En este caso se implementa el que afecta a la finalización del job para que muestre un mensaje en el log:

/**
* @author lagarcia
*
*/
@Component
public class BatchListener extends JobExecutionListenerSupport {

/** A logger reference */
private static Logger logger = Logger.getLogger(BatchListener.class);

/**
* After job execution.
*/
@Override
public void afterJob(JobExecution jobExecution) {
  if (jobExecution.getStatus() == BatchStatus.COMPLETED) {
    logger.info("¡¡Job " + jobExecution.getJobId() + " finalizado!!");
  }
}
}

/**

* @author lagarcia

@Component

public class BatchListener extends JobExecutionListenerSupport {

/** A logger reference */

private static Logger logger = Logger.getLogger(BatchListener.class);

/**

* After job execution.

@Override

public void afterJob(JobExecution jobExecution) {

if (jobExecution.getStatus() == BatchStatus.COMPLETED) {

logger.info("¡¡Job " + jobExecution.getJobId() + " finalizado!!");

}

5. Ejecución

Al lanzar la aplicación podemos ver en los logs que el job se ejecutó correctamente (y tb al acceder a los datos desde la página web).

Logs de Spring Batch

GUI web

Se puede descargar el proyecto completo desde aquí. Y también en Github.