Chapter 7 of the IREn InGrid User Guide

Using IREn InGrid in Fairy mode

In Fairy mode, IREn InGrid works as a network server. It accepts SOAP or REST requests, takes source documents along with their resources, and performs formatting via one or more instances of IREn formatters. In Fairy mode, IREn InGrid also performs load balancing between the underlying formatters.

IREn InGrid in Fairy mode is supposed to be accessed from within the client's custom software which is a part of your company's document processing environment. Simply speaking, the user (you) are required to write a relevant piece of Client program and configure it to access the Fairy. Since Fairy accepts SOAP requests, there are very few limitations on the platforms or programming languages to use; virtually any SOAP toolkit would fit, depending on your needs.

Before using IREn InGrid in Fairy mode, it must be configured accordingly. See Chapter 3 for further details.

7.1. SOAP API

Fairy, as a SOAP service, provides with two methods: to format and to stop. If not otherwise specified in configuration, methods names are format and stop, respectively.

format Method takes two arguments: systemId and xml. systemId is the document's system identifier. xml is XSL-FO document, or XML with an embedded stylesheet (see Section 2.5). Also see Section 7.6.
stop The call of this method stops Fairy as soon as it becomes free. Any following requests will not be served.

Fairy provides with a WSDL document describing the service. For example, if Fairy is running at host yourhost with the default configuration, you can get the WSDL document by sumbitting GET /fairy?WSDL HTTP request to yourhost:6577 (e.g., just by typing http://yourhost:6577/fairy?WSDL in browser's address field).

Fairy, as a SOAP service, returns one of the following status codes:

200 OK The request has succeeded. The response body contains formatted document.
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

See Section 7.3 for further details on commands and their arguments.

7.2. REST API

REST API is de-facto the standard approach for modern network APIs. In recent years, SOAP has been rarely used for new projects and is often replaced with the REST API because of the simplicity of the latter. REST API works in a pretty much the same way as SOAP over the same HTTP connection, but it does not require XML wrapping and Base64 encoding for both request and response. Avoiding double encoding and wrapping results in smaller network traffic and lower CPU usage and therefore provides with better overall performance (on small documents 7-10%). Writing a client code for REST API and supporting it appears simpler and faster because it consists of sending HTTP request with a raw document data and receiving a raw formatting result without requiring any additional wrapping or encoding.

A simple HTML form example for submitting a document for formatting via the Web browser:

<html><body><div>
    <form action="http://localhost:6577/format" method="POST"
             enctype="multipart/form-data">
        <label>Document to format:</label>
        <input type="file" name="upload_file[]"/>
        <label>SystemId:</label>
        <input type="url" name="systemId[]" value=""/>
        <input type="submit" value="Submit"/>
    </form>
</div></body></html>

This example can be saved as an .html file and opened in a Web browser to submit documents (assuming that IREn InGrid is running locally), or the form part can be integrated in any other Web site. A bit more user-friendly version of this example is included in the IREn InGrid distribution and is accessible at /format directory.

Note: If the API is used by the JavaScript code (Ajax) instead of submitting a form, Access-Control-Allow-Origin option must be set to *.

7.3. API Endpoint list

The following API endpoints are available:

Table 7.1. API Endpoints

HTTP method	URI path	Request Content Type	Description
POST	/fairy	text/xml	Accepts SOAP formatting requests.
GET	/fairy?WSDL		Retrieves WSDL for Fairy SOAP service.
POST	/format	multipart/form-data	The Request must contain a `systemId[]` and `upload_file[]` entries. Returns a formatted document from `upload_file[]` entry with all relative resources resolved relatively URL from the `systemId[]` entry.
GET	/format		Retrieves a Web page with a form for submitting documents to process.
POST	/formatFO	text/xml	Accepts an XSL-FO file for formatting. If the FO file contains relatively-referenced resources, the URL must contain a query with a `systemId` parameter, having the value of an URL-encoded `systemId` (base URL for resolving relative URLs in the document. For example: `/formatFO?systemId=file%3A%5CC%3A%5CProgram+Files%5C?RenderX%5CXEP%5Cexamples%5Cbasic%5Cbgimage.fo`
POST	/formatZIP	application/zip	Accepts a ZIP binary file containing a source FO or XML+XSL or XEPOUT file. IREn InGrid will automatically detect the file to start from. The ZIP archive may have any name. The archive can also contain bundled resources such as images. If the `systemId` is not specified via the URL query, the `systemId` will be set to the ZIP file contents; therefore allowing resource bundling.
GET	/	text/xml	Retrieves a page containing a brief description of Fairy service and links to a page containing a document submitting form and page with API description.

If the formatting request fails, the server will return 500 Content-Type: "text/plain" with the detailed description of the failure.

7.4. Transport Layer Security

Fairy supports TLS (Transport Layer Security) that allows sending sensitive documents securely via insecure networking transport. In this case, the clients are ensured they are connecting to an authentic server.

Fairy also supports two-way TLS, limiting access to authorized clients only. In this case, it stores public keys of all authorized clients and verifies the keys on each request.

IREn InGrid distribution contains a sample of Fairy client application. One may find it in etc\JavaClient\ within the IREn InGrid installation directory. The application shows how to use one-way and two-way TLS with Fairy.

7.5. Load Balancing

Fairy also acts as a load-balancer. Upon arrival, all new incoming formatting requests are internally queued. Once an Agent is available, it starts processing the first queued formatting request.

The queue length may be configured. If the limit is reached, e.g. the queue is full, and a new request arrives, it gets rejected with Error 503 Service Temporary Unavailable status code and a warning is logged. Since the queue keeps open connection sockets, the queue length is actually limited by the amount of free sockets in OS' TCP stack. Normally, this limit should not be reached, and the fact that it is being actually reached usually means that the hardware configuration is insufficient for the purpose of effective load balancing.

7.6. Supported Encodings

Fairy will accept SOAP request without the type specification for method's arguments. In this case format method's first argument will be interpreted as 'string' (and will be used without any conversion) and the second argument as 'base64Binary', but for greater compatibility it suggests the following types for arguments:

'base64' or 'base64Binary' data is Base64-encoded.
'arrayType' data is represented as array of bytes.
'string' data is represented as is (and will be used without any conversion).

Here are examples of SOAP requests:

...
<format>
    <systemId>SYSTEMID</systemId>
    <xml>XML_DATABASE64ENCODED</xml>
</format>
...

...
<format>
    <systemId xsi:type="xsd:string">SystemId</systemId>
    <xml xsi:type="xsd:base64Binary">XML_DATA_BASE64_ENCODED</xml>
</format>
...