Introduction

Use the Http Listener connector to receive RESTFul requests and to feed these requests to an Aspire pipeline. This feeder can turn Aspire into a "RESTful Web Service", accepting requests from outside clients, processing jobs, and then returning results.

The Http Listener connector will register a new endpoint URL, based on the Aspire server path. For example, if your seed description is "http seed" and endpoint name is "submitFiles" , then the new URL will be http://localhost:50505/aspire/_api/http_seed/submitFiles/. Look that the underscore replaced space in words "http seed".  In other words, it is separate and apart from the standard Aspire admin user interface (which is under "/aspire").

There are two modes of operation for the HTTP Feeder: 1) Input parameters specified on the URL, and 2) Input data POST'ed to the feeder. In the case of parameters on the URL, the input parameters are added to the AspireObject which is fed down the pipeline. In the case of POSTed data, this may either be parameters from a form that will be added to AspireObject which is fed down the pipeline or data streamed to the endpoint which is attached to the published Job as a stream.

The HTTP Feeder can also be used to upload files, using a Multipart form submission. See below for details.

Repository

Connector Features

Connector Features

The Http Listener connector has the following features:

• Parameters Specified on the URL written to AspireObject.
• Serving files.
• Xml and JSON Data POSTed to service are sent to Aspire pipeline.
• Upload file by Multipart Form Submissions.

Parameters Specified on the URL

In the first mode, parameters are specified on the URL in param=value format. For example: http://localhost:50505/aspire/_api/http_seed/mySeed/params?param1=value1&param2=value2 .

These parameters will be stored in the resulting AspireDocument passed down the pipeline as XML tags at the top level. For example:

 <doc>
   <feederLabel>HttpFeeder</feederLabel>
   <param1 source="FeederReleaseEndpoint">value1</param1>
   <param2 source="FeederReleaseEndpoint">value2</param2>
 </doc>

The pipeline would then be responsible (via groovy scripting or whatever) for processing the job as necessary. The results would be returned as XML data.

Information from the Endpoint

Information from the endpoint is also added to the job published by the HTTPFeeder Information is added as elements to the <aspireHttpFeederEndpoint> tag:

 <doc>
  <feederLabel>httpFeeder</feederLabel>
  <param source="FeederReleaseEndpoint">1</param>
  <param source="FeederReleaseEndpoint">2</param>
  <aspireHttpFeederEndpoint fullPath="/aspire/_api/http_seed/mySeed/parameters" relativePath="/parameters" remoteAddr="[0:0:0:0:0:0:0:1]" remoteHost="[0:0:0:0:0:0:0:1]" remotePort="63173" serverName="localhost" serverPort="50505" endpointPath="/aspire/_api/http_seed/mySeed" source="FeederReleaseEndpoint">
  <queryString>param=1&param=2</queryString>
  </aspireHttpFeederEndpoint>
  <pathInfo source="FeederReleaseEndpoint">/parameters</pathInfo>
</doc>

The following information is available:

XML and JSON Data POSTed to the Service

If you wish to actually post data to the service, this can currently be done by setting the "Accept posted content" parameter to TRUE.

The content can be XML or JSON. 

This also means that you can follow the HTTP feeder with any pipeline stage that uses the content stream. For example, XML Sub Job Extractor, Tabular Files Extractor_Aspire_2, XML File Loader, and Extract Text can all be the first pipeline stage to receive the job.

The relative url looks like aspire/_api/#{seed description}/#{endpoint}/data.

See the examples below to understand how to use it.

JSON input:

curl -X POST --location "http://localhost:50505/aspire/_api/http_seed/mySeed/data" \
    -H "Content-Type: application/json" \
    -d "{\"name\" : \"David\", \"lastName\": \"Grobelny\"}"

JSON output:

{"doc":{"name":"David","lastName":"Grobelny","aspireHttpFeederEndpoint":{"@source":"FeederReleaseEndpoint","@serverPort":"50505","@serverName":"localhost","@endpointPath":"\/aspire\/_api\/http_seed\/mySeed","@relativePath":"\/data","@fullPath":"\/aspire\/_api\/http_seed\/mySeed\/data","@remoteAddr":"127.0.0.1","@remoteHost":"127.0.0.1","@remotePort":"61250"},"pathInfo":{"@source":"FeederReleaseEndpoint","$":"\/data"}}}

XML input:

curl -X POST --location "http://localhost:50505/aspire/_api/http_seed/mySeed/data" \
    -H "Content-Type: application/xml" \
    -d "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>
<DATA_RECORD>
<APPLICANT_ID>11130154</APPLICANT_ID>
<ROLES>accounts assistant</ROLES>
<MAIN_SKILLS>sage line, excel, word power point</MAIN_SKILLS>
<TEXT_CV>manager executive construction project manager</TEXT_CV>
</DATA_RECORD>"

XML output:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <DATA_RECORD>
        <APPLICANT_ID>11130154</APPLICANT_ID>
        <ROLES>accounts assistant</ROLES>
        <MAIN_SKILLS>sage line, excel, word power point</MAIN_SKILLS>
        <TEXT_CV>manager executive construction project manager</TEXT_CV>
    </DATA_RECORD>
    <aspireHttpFeederEndpoint endpointPath="/aspire/_api/http_seed/mySeed" fullPath="/aspire/_api/http_seed/mySeed/data"
                              relativePath="/data" remoteAddr="127.0.0.1" remoteHost="127.0.0.1" remotePort="65372"
                              serverName="localhost" serverPort="50505" source="FeederReleaseEndpoint"/>
    <pathInfo source="FeederReleaseEndpoint">/data</pathInfo>
</doc>

XML input with XSLT template path enable "Transform response" and fill path "/config/xsl/extractor.xsl" to the field "Transform file". You need to put file "extractor.xsl" to "aspire5/config/xsl" folder.

curl -X POST --location "http://localhost:50505/aspire/_api/http_seed/mySeed/data" \
    -H "Content-Type: application/xml" \
    -d "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>
<DATA_RECORD>
<APPLICANT_ID>11130154</APPLICANT_ID>
<ROLES>accounts assistant</ROLES>
<MAIN_SKILLS>sage line, excel, word power point</MAIN_SKILLS>
<TEXT_CV>manager executive construction project manager</TEXT_CV>
</DATA_RECORD>"

XML output will be related to xsl schema file.

<?xml version="1.0" encoding="UTF-8"?>
<doc type="APPLICANT" id="11130154"/>

Multipart Form Submissions

HTML supports submitting "multipart forms" made up of multiple parameters, some of which may represent uploaded file content.

In order for the HTTP feeder to receive multipart forms, you need to enable them and then specify how files are handled. You may choose to handle posted files as a stream (choose stream for the "Multipart form data" option), or as files (choose file for the "Multipart form data" option). If you choose to handle posted files as files, you must also specify the directory they are uploaded to.

Note: setting the "Accept posted content" option of the HttpFeeder automatically disables multipart form submission processing.

The relative url looks like aspire/_api/#{seed description}/#{endpoint}/form.

See the examples below to understand how to use it.

Stream Handler

When the file handler is set to stream, only a single file may be uploaded at a time. Also, all parameters which are received BEFORE the file will be added to the job's as XML tags on the AspireObject. Parameters received AFTER the file are ignored. The file itself will be attached as an InputStream to the job and subsequent stages can access the data using the Standards.Basic.getContentStream(Job j) method in the package com.accenture.aspire.framework and so data can be streamed directly from the client through whatever processing you need to do. The file is NOT stored locally on the Aspire server by the HttpFeeder.

Input:

curl -X POST --location "http://localhost:50505/aspire/_api/http_seed/mySeed/form" \
    -H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
    -F "field-name=@C:\tmp\multipartfile.txt;filename=file.txt;type=*/*"

Output:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <field-name source="FeederReleaseEndpoint">file.txt</field-name>
    <contentStream>Http Feeder

        Description: Feeds a single URL down the pipeline in response to an http request.
		...
        
    </contentStream>
    <aspireHttpFeederEndpoint endpointPath="/aspire/_api/http_seed/mySeed" fullPath="/aspire/_api/http_seed/mySeed/form"
                              relativePath="/form" remoteAddr="127.0.0.1" remoteHost="127.0.0.1" remotePort="63025"
                              serverName="localhost" serverPort="50505" source="FeederReleaseEndpoint"/>
    <pathInfo source="FeederReleaseEndpoint">/form</pathInfo>
</doc>

File Handler

When the file handler is set to file, multiple files may be uploaded by a single form submission. Using the file handler requires the Http Listener field Upload directory name to be configured. Any file submitted will be uploaded and saved to this directory. The uploaded file is saved using its original filename (filename only, not the complete path).

No streams are added to the Aspire job, and if you wish to reference the file, you will need to access the job's AspireObject and extract the value for the tag corresponding to the HTML form input that caused the file to be uploaded. This value is the full path to the saved copy of the uploaded file on the Aspire server.

For example, we will use same input as it was for Stream handler.

Input:

curl -X POST --location "http://localhost:50505/aspire/_api/http_seed/mySeed/form" \
    -H "Content-Type: multipart/form-data; boundary=WebAppBoundary" \
    -F "field-name=@C:\tmp\multipartfile.txt;filename=file.txt;type=*/*"

Output:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <field-name source="FeederReleaseEndpoint">
        c:\Users\david.grobelny\aspire5.1\target\aspire-distribution-archetype-5.1-SNAPSHOT-distribution/config/xsl\file.txt
    </field-name>
    <aspireHttpFeederEndpoint endpointPath="/aspire/_api/http_seed/mySeed" fullPath="/aspire/_api/http_seed/mySeed/form"
                              relativePath="/form" remoteAddr="127.0.0.1" remoteHost="127.0.0.1" remotePort="56743"
                              serverName="localhost" serverPort="50505" source="FeederReleaseEndpoint"/>
    <pathInfo source="FeederReleaseEndpoint">/form</pathInfo>
</doc>

Configuration

Serving Files

The HTTPFeeder can also serve up ordinary HTML files so it can be used as a more complete, end-to-end user interface for simple user interfaces.

Files are stored inside the Aspire Home directory, in the "$ASPIRE_HOME/web/httpfeeder/#{endpoint}/#{html_serving_directory}" directory.

For example, a request for:

• http://localhost:50505/aspire/_api/http_seed/mySeed/submitFiles/test.html

Will access the file from:

• $ASPIRE_HOME/web/httpfeeder/mySeed/submitFiles/test.html

Note that “index.html” is also supported. So, a request for:

• http://localhost:50505/aspire/_api/http_seed/mySeed/submitFiles/

Will return:

• $ASPIRE_HOME/web/httpfeeder/mySeed/submitFiles/index.html

If it exists.