Connector Configuration Reference

The file connector.xcf is the configuration file for the Genero Application Server (GAS) Connector. The file is stored in the Web Server’s CGI binaries directory.

Syntax:

<CONFIGURATION> <CONNECTOR> <INTERFACE_TO_APPLICATION_SERVER> ... </INTERFACE_TO_APPLICATION_SERVER> <REQUEST_LIST> ... </REQUEST_LIST> <ERROR_LIST> ... </ERROR_LIST> </CONNECTOR> </CONFIGURATION>

Notes:

One CONFIGURATION element. The main element of all configuration files. There are no attributes for the CONFIGURATION element.
One CONNECTOR element. A connector is uniquely defined in the configuration file. There are no attributes for the CONNECTOR element.
Zero or one INTERFACE_TO_APPLICATION_SERVER element. This section defines the parameters necessary to access the Application Server by providing the application port definition section.
One REQUEST_LIST element. This section lists all the requests to be forwarded to the Application Server. A request can be made for a Web Service or a Web Application. The request forwarding section.
Zero or one ERROR_LIST element. This section contains all errors that the connector can produce, and specifies which files are displayed when an error occurs.

Back to the top

INTERFACE_TO_APPLICATION_SERVER

Within the INTERFACE_TO_APPLICATION SERVER element, you specify the base port for the Genero Application Server Connector. The base port specifies which port will be used in conjunction of the offset specified in each server.

Syntax:

<CONFIGURATION> <CONNECTOR> <INTERFACE_TO_APPLICATION_SERVER> <TCP_BASE_PORT> port </TCP_BASE_PORT> </INTERFACE_TO_APPLICATION_SERVER> request_list section error_list section </CONNECTOR> </CONFIGURATION>

Notes:

port is the base port number. This number is added to the port offset specified in a SERVER element within the REQUEST_LIST section. Usually, this base port corresponds to the TCP_BASE_PORT for the Genero Application Server, defined in the INTERFACE_TO_CONNECTOR section of the Genero Application Server configuration file.
The default value for the TCP_BASE_PORT element is 6300.
There are no attributes available for the TCP_BASE_PORT element.

Example:

01 <INTERFACE_TO_APPLICATION_SERVER>
02   <TCP_BASE_PORT>6300</TCP_BASE_PORT>
03 </INTERFACE_TO_APPLICATION_SERVER>

Back to the top

REQUEST_LIST

The REQUEST_LIST element lists all the requests to be forwarded to the Application Server. A request can be made for a Web Service or a Web Application. This section defines the ports where application servers are listening for requests. At least one default server must be specified, although multiple default servers can be listed to provide load balancing for performance. Application-specific application servers can also be specified.

Syntax:

<CONFIGURATION> <CONNECTOR> interface_to_application_server section <REQUEST_LIST> <DEFAULT> <SERVER> defserver:offset </SERVER> [ ... ] </DEFAULT> rqServer [...] </REQUEST_LIST> error_list section </CONNECTOR> </CONFIGURATION>

where rqServer is:

<REQUEST Id="appName"> <SERVER>appServer:offset</SERVER> [...] </REQUEST>

Notes`:`

defserver is the default application server name or IP address.
NOTE: When configuring the connector for participation in a solution that includes Kerberos authentication, you must specify the fully-qualified name of the server (as shown in Example 2 below).
offset is the offset port number for an application server. This value, when added to the application server base port (specified in the INTERFACE_TO_APPLICATION_SERVER section), identifies the port where the application server is listening for requests. For example, the default port for GAS is 6394 (the base port of 6300 + the offset of 94).
You can only specify one DEFAULT element. Within the DEFAULT element, you can specify multiple SERVER elements.
appName is the unique identifier (Id) of either the Web Application or the Web Service, as defined in the Genero Application Server configuration file for the specified appserver or in an external application configuration file accessible by the Genero Application Server specified by appserver.
appServer is a Genero Application Server server name or IP address.
You can specify multiple REQUEST elements. A request is defined by its required Id attribute. The Id attribute must either match an application Id specified for an APPLICATION element in the Genero Application Server configuration file, a Web Service Id specified in the Genero Application Server configuration file, or the filename of an external application configuration file accessible by the Genero Application Server. If the Id does not match either of these, the GAS Connector will answer requests for this Id with a "404 object not found" error.
There are no available attributes for the REQUEST_LIST, DEFAULT, and SERVER elements.

Example 1:

01 <REQUEST_LIST>
02   <DEFAULT>
03     <SERVER>localhost:94</SERVER>
04     <SERVER>localhost:95</SERVER>
05   </DEFAULT>
06   <REQUEST Id="Edit">
07     <SERVER>localhost:96</SERVER>
08   </REQUEST>
09 </REQUEST_LIST>

In this example, if the called application is "Edit", the request is redirected to the application server launched on port 6396 (base port + offset), otherwise the request is sent to one of the default servers listening on ports 6394 and 6395.

Example 2:

01 <REQUEST_LIST>
02   <DEFAULT>
03     <SERVER>myserver.mydomain.com:94</SERVER>
04   </DEFAULT>
05 </REQUEST_LIST>

In this example, the fully-qualified domain name is used to define the server. You must use a fully-qualified domain name when using Kerberos authentication.

Back to the top

ERROR_LIST

The ERROR_LIST element specifies what information is displayed when specific errors occur.

Syntax:

<CONFIGURATION> <CONNECTOR> interface_to_application_server section request_list section <ERROR_LIST> <ERROR Id="errID"> <HTTP_STATUS> status </HTTP_STATUS> <HTTP_HEADER Id=" header"> headerValue </HTTP_HEADER> <BODY_FILE> filename </BODY_FILE> </ERROR> [ ... ] </ERROR_LIST> </CONNECTOR> </CONFIGURATION>

Syntax:

<ERROR_LIST>
   error [...]
</ERROR_LIST>

where error is:

<ERROR Id="code">
  <HTTP_STATUS> status </HTTP_STATUS>
  <HTTP_HEADER Id="header"> value </HTTP_HEADER>
  <BODY_FILE> filename </BODY_FILE>
</ERROR>

Notes:

code is the error code; a string value specifying the connector error identifier. There are six different error codes:

Error Code Description

1 Application ID not specified.

2 Unable to find the configuration.

3 Application not found.

4 Cannot connect to the Application Server.

5 Cannot connect to the Application Server any longer.

6 Connection lost between the Connector and the Application Server.

status is the http status associated to this error, such as:
```
400 Bad Request
```
HTTP status to return when the error occurs.
header is the header variable name, such as:
```
Pragma
```
value is the header variable value, such as:
```
no-cache
```
When set to no cache, it directs the browser to not keep the file in the cache. The headers are put before the error message, like cache control, redirection, and so on.
filename is the name of the file associated to this error. The file contains the html to display when the error is encountered, and is located in your Web Server script directory (the same directory that stores the connector.xcf file).

Genero Web Services Notes:

For SOAP errors, status is ignored and set to "500 Internal Server Error" as specified in Simple Object Access Protocol (SOAP) 1.1 - 6.2 SOAP HTTP Response.

Example:

01 <ERROR_LIST>
02   <ERROR Id="1">
03     <HTTP_STATUS>400 Bad Request</HTTP_STATUS>
04     <HTTP_HEADER Id="Pragma">no-cache</HTTP_HEADER>
05     <BODY_FILE>connector-error-1</BODY_FILE>
06   </ERROR>
07   <ERROR Id="2">
08     <HTTP_STATUS>500 Internal Server Error</HTTP_STATUS>
09     <HTTP_HEADER Id="Pragma">no-cache</HTTP_HEADER>
10     <BODY_FILE>connector-error-2</BODY_FILE>
11   </ERROR>
12   <ERROR Id="3">
13     <HTTP_STATUS>404 Not Found</HTTP_STATUS>
14     <HTTP_HEADER Id="Pragma">no-cache</HTTP_HEADER>
15     <BODY_FILE>connector-error-3</BODY_FILE>
16   </ERROR>
17   <ERROR Id="4">
18     <HTTP_STATUS>503 Service Unavailable</HTTP_STATUS>
19     <HTTP_HEADER Id="Pragma">no-cache</HTTP_HEADER>
20     <BODY_FILE>connector-error-4</BODY_FILE>
21   </ERROR>
22   <ERROR Id="5">
23     <HTTP_STATUS>503 Service Unavailable</HTTP_STATUS>
24     <HTTP_HEADER Id="Pragma">no-cache</HTTP_HEADER>
25     <BODY_FILE>connector-error-5</BODY_FILE>
26   </ERROR>
27   <ERROR Id="6">
28     <HTTP_STATUS>502 Bad Gateway</HTTP_STATUS>
29     <HTTP_HEADER Id="Pragma">no-cache</HTTP_HEADER>
30     <BODY_FILE>connector-error-6</BODY_FILE>
31   </ERROR>
32 </ERROR_LIST>

This example is taken from the default settings in the GAS Connector configuration file.

Back to the top

Error Code	Description
1	Application ID not specified.
2	Unable to find the configuration.
3	Application not found.
4	Cannot connect to the Application Server.
5	Cannot connect to the Application Server any longer.
6	Connection lost between the Connector and the Application Server.