/fen2chessboard

RESTful Web service generating chess diagrams from FEN strings

Primary LanguageJavaMIT LicenseMIT

FEN2Chessboard

==============

This is a simple Web application that generates chess diagrams from Forsyth-Edwards notation (FEN) strings.

The core module can also be used as an autonomous library to generate chess diagrams. Please check the documentation of the module for this use case.

It runs as a RESTful Web service: you provide your FEN string in the URL, as well as some other optional parameters, and you receive an image with the diagram.

For example:

The application runs at http://localhost:8080/fen2chessboard-rs/fen2cb

The FEN string for the starting position in chess is

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

So you type in your browser:

http://localhost:8080/fen2chessboard-rs/fen2cb/rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

And you get the image:

Default diagram style

Please note that only the part of FEN that describes the position is used in the URL. The side to move ('w' or 'b') element may be used to flip the view. Other FEN items (castling, en passant) are not used.

==============

Project Contents

The project currently contains two modules and a folder with resources. They all are placed under components folder:

.
├── components
    ├── core
    ├── service
    └── styles

The core module contains the main logic of the application and may be re-used as a library for chess diagrams generation.

The service module contains an implementation of a RESTful Web service based on Jersey framework.

The styles folder contains the definitions of resources featured with the application: graphic diagram styles and their configuration.

==============

Options

  • Flip the board by adding /b or /B to the URL. Default is the view for White (/w or /W is implicit at the end of the URL, but may be added).

  • Request a specific size of the image by adding ;size=X to the URL, where X is the number of pixels for the height or the width of the diagram. Diagrams are square, so there is no need to have two separate parameters for that. size=0 is interpreted as default size, which corresponds to the size of the source chess board image.

  • Request a specific graphic style for the image by adding ;style=N to the URL, where N is the name of the style. Diagram graphic styles may be created and configured at any moment, without the need to change the code of the application. To modify an existing style or create a new one, please check the documentation.

The following styles are provided:

  1. default style (the diagram above). This style is used if the style parameter is not set or empty, or if it is explicitly set to 'default'.

  2. wiki style:

Wiki diagram style

  1. leipzig style:

Leipzig diagram style

  1. text style - ASCII representation of the chess board
---------------------------------
| r | n | b | q | k | b | n | r |
---------------------------------
| p | p | p | p | p | p | p | p |
---------------------------------
|   |   |   |   |   |   |   |   |
---------------------------------
|   |   |   |   |   |   |   |   |
---------------------------------
|   |   |   |   |   |   |   |   |
---------------------------------
|   |   |   |   |   |   |   |   |
---------------------------------
| P | P | P | P | P | P | P | P |
---------------------------------
| R | N | B | Q | K | B | N | R |
---------------------------------

Thus, the URL pattern to call the service is the following:

{host}/fen2chessboard-rs/fen2cb/{FEN-position}[/side][;size=int][;style=string]

You can try in action a demo version of the service.

==============

Errors Management

If an error occurs, the application replies with a JSON message (application/json MIME type) having the following structure:

{
    "status": [HTTP response code],
    "message": [error message]
}

Typical messages for client-side error reponses are:

Invalid FEN string: 'rnbqkbnr/ppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR/w'

Failed to find the style 'wiky'. Please check its name.

Invalid size: 10000. Must be between 0 and 2048.

They are sent if at least one of the request parameters is invalid.

==============

Installation

Pre-requisites:

  • Java 8
  • Maven 3
  • Apache Tomcat instance, or any other Web application container capable to deploy .war files. The application has been developed and tested using Tomcat 7.

Steps:

  1. Check out the project code, as you are used to on GitHub.

  2. Switch to the project folder and type

mvn clean install

The output should succeed with something like

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] FEN to Chess Diagram Web Service .................. SUCCESS [  1.087 s]
[INFO] FEN2Chessboard Core Library ....................... SUCCESS [  8.311 s]
[INFO] FEN2Chessboard Web Service ........................ SUCCESS [  3.119 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12.642 s
[INFO] Finished at: 2014-11-11T15:58:19+01:00
[INFO] Final Memory: 22M/325M
[INFO] ------------------------------------------------------------------------
  1. Copy the components/styles folder into the lib/fen2chessboard folder in your Tomcat. This should result in the following folders structure:
{TOMCAT_HOME}
├── bin
├── conf
├── lib
│   └── fen2chessboard
│       └── styles
│           ├── default
│           ├── leipzig
│           └── wiki
├── logs
├── temp
├── webapps
├── work

  1. Put a log4j.properties file in {TOMCAT_HOME}/lib, if you want some logging features (may be useful for tracing server-side errors).

  2. Ensure that your Tomcat is running. Deploy the web application from components/service/target/fen2chessboard-rs.war using your favorite method. You may deploy it using the Maven command

mvn tomcat7:undeploy tomcat7:deploy

Please check the respective Maven plugin configuration in components/service/pom.xml.

Your application instance should be functional now.