Skip to content

Home

Jump to bottom
Juraj Sranko edited this page Oct 19, 2020 · 36 revisions

si-iws-builder (IWS Builder)

si-iws-builder is an opensource library to save IBM IWS (IBM Integrated Web services Server) server definition in text/JSON format. WebService definition in text format brings the following advantages:

  • reusable
  • traceable
  • save creation time
  • save time for changes
  • ... and much more

The library is based on IBMs collection of Qshell commands. For more details see here Integrated Web Services for IBM i - Web services made easy

How to create IWSS definition

IWSS (Integrated Web application Server Source) describes services for one server.

{
    "server": {
        "name": "SIIIA",
        "port": 16787,
        "userId": "QWSERVICE",
        "noHttp": true,
        "version": "*CURRENT",
        "printErrorDetails": false
    },
    ...
}

server - Describe a new integrated Web services server with the specified name. The name must be unique.

  • name - Specifies the name of the web services server to be created
  • port - Specifies the starting port number for generating ports required by the web services server. On creation, a port block of 10 ports is assumed to be available for the server, starting from the specified starting-port, although only four ports are used by default
  • userId - Specifies the user profile the web services server will run under. If not specified, QWSERVICE will be used, unless the caller of the command does not have authority to use the profile, in which case the caller's profile will be used. If a user ID is specified, the command will fail if the user profile of the caller of the command does not have *ALLOBJ or *USE authority to the specified user ID.
  • noHttp - Indicates that an associated HTTP server should not be created. If not specified, an associated HTTP server is created.
  • version - Indicating which version of web services server should be created. If a value of *DEFAULT is specified, the default version of a web services server for the installed operating system release will be created. If a value of *CURRENT is specified, the most current version of web services server for the installed release will be created. If not specified, a value of *DEFAULT will be used.
  • printErrorDetails - Indicates that additional error information, such as stack traces and error codes, should be shown if the command fails.
{
    ...
    "services": [
        {
            "name": "SIROUTER",
            "programObject": "/QSYS.LIB/$(LIBRARY).LIB/SIROUTER.PGM",
            "userId": "*SERVER",
            "detectFieldLengths": true,
            "serviceType": "*REST",
            "host": "localhost",
            "targetNamespace": null,
            "propertiesFile": "/tmp/SIROUTER.propertiesFile",
            "libraryList": "SIIIA:QTEMP",
            "libraryListPosition": "*FIRST",
            "transportMetadata": "REMOTE_ADDR:REMOTE_USER:REQUEST_METHOD:REQUEST_URL:REQUEST_URI:QUERY_STRING:SERVER_NAME:SERVER_PORT",
            "transportHeaders": null,
            "useParamNameAsElementName": false,
            "properties": [
                ...
            ]
        }
    ]
}

services - Describe Web Services to be created.

  • name - Specifies the name of the web service. If not specified, the program object name will be used.
  • programObject - Specifies the integrated file system path to the ILE program or service program that will be deployed as a web service.
  • userId - Specifies the user profile the web service will run under. If not specified, the web service will run under the web services server user profile. A value of *SERVER will ensure the web service runs under the same user profile as the web services server. the same user profile as the web services server. A value of *AUTHENTICATED will ensure the web service runs under an authenticated user profile.
  • detectFieldLengths - Indicates that field lengths for array and character fields will be detected. Specifying a field length for output arrays ensures only those elements that are set in the array are returned. Specifying a length field for large character fields improves the processing of the character field. If not specified, length field processing is not performed.
  • serviceType - Specifies the type of service to be installed. A value of *SOAP11 or *SOAP12 indicates that the program object should be installed as a SOAP 1.1 or SOAP 1.2 service, respectively. A value of *REST indicates that the program object should be installed as a REST service. If not specified the default value of *SOAP11 is used.
  • host - Specifies the host name or internet protocol (IP) address of the server hosting the web service implementation code (i.e. ILE program object). Specify localhost if the web service implementation code resides on the same server as the integrated web services server. A secure channel between the server and the server hosting the web service implementation code may be requested by appending :SECURE to the host value. For example, -host iserver.com:SECURE.
  • targetNamespace - Relevant for SOAP messages.
  • propertiesFile - Specifies an absolute path to file that contains various web service properties. The property file is created by IWS Builder. See Key "properties". The property file follows the rules of Java properties file. For example, to indicate a line is a comment, you would start the line with a pound sign ('#'). REST properties such as the URI path template, HTTP request method, and the content type of the response may be specified in the file for each entry point in the program object.
  • libraryList - Specifies a list of libraries that will be added to the library list prior to invoking the web service. Each library in the list must be delimited by a colon.
  • libraryListPosition - Specifies the position in the user portion of the job library list where the list of libraries specified in - libraryList will be placed. A value of *FIRST inserts the libraries at the beginning of the user portion of the library list. A value of *LAST inserts the libraries at the end of the user portion of the library list. If not specified, a value of *LAST will be used.
  • transportMetadata - Specifies what transport metadata to pass to the web service implementation code. Transport metadata is passed as environment variables. The default value of *NONE indicates that no metadata is set. A colon delimited string of metadata can also be specified. Supported value(s): REMOTE_ADDR, REMOTE_USER, REQUEST_METHOD, REQUEST_URL, REQUEST_URI, QUERY_STRING, SERVER_NAME and SERVER_PORT.
  • transportHeaders - Specifies what transport headers (e.g. HTTP headers) to pass to the web service implementation code. Transport headers are passed as environment variables. The environment variable name for HTTP headers is made up of the specified HTTP header prefixed with 'HTTP_', all uppercased. For example, if 'Content-type' is specified, then the environment variable name would be 'HTTP_CONTENT-TYPE'. The default value of *NONE indicates that no transport headers should be set. A colon delimited string of transport headers can also be specified.
  • useParamNameAsElementName - Indicates whether the element name should be matched to the parameter name for the wrapper element in XML payloads. If specified, the wrapper element name will match the parameter name. If not specified, the wrapper element name will match the structure name. This parameter is ignored for SOAP services. This parameter is optional.
    "properties": [
        {
            "SIROUTER.uri.path.template": null,
            "SIROUTER.http.request.method": "GET",
            "SIROUTER.wrap.input.parameters": false,
            "SIROUTER.wrap.output.parameter": false,
            "SIROUTER.consumes": "application/json",
            "SIROUTER.produces": "application/json",
            "SIROUTER.response.code.parameter": "RESPONSECODE",
            "SIROUTER.http.headers.parameter": "RESPONSEHEADERS",
            "SIROUTER.PAYLOADIN.usage": "input",
            "SIROUTER.PAYLOADOUT.usage": "output",
            "SIROUTER.RESPONSECODE.usage": "output",
            "SIROUTER.RESPONSEHEADERS.usage": "output",
            "responses": {
                ...
            }
        }
    ]

properties - The properties follow the rules of Java properties file. For more details see Integrated Web Services Server Administration and Programming Guide

    "responses": {
        "200": {
            "description": "Successful operation XXXXXX"
        },
        "400": {
            "description": "yyyyyyy"
        }
    }

responses - Describe responses for operation with HTTP code and description.

How to use IWS Builder

To use IWS Builder a JAR file with all dependencies is required. IWS Builder is a Maven project, therefore JAR files can be created with Maven or the latest version of JAR files can be downloaded from GITHUB.

Use without Maven (download from GitHub)

For download, a .jar file you will need install some dependencies

yum install curl jq

Download the latest version of .jar file

curl http://files.sranko-informatik.de/getGithubPackage.php?package=si-iws-builder-latest --output si-iws-builder-jar-with-dependencies.jar --insecure

Use with Maven

Go into the target directory

cd si-iws-builder/IWSBuilder/target

Use the app

  1. Run with the configuration from ifs
java -cp si-iws-builder-jar-with-dependencies.jar 
     de.sranko_informatik.ibmi.iwsbuilder.App "/home/cecuser/si-iws-builder/IWSBuilder/src/main/qiwsssrc/HELLOWORLD.IWSS"
  1. Run with the configuration from QSYS.LIB
java -cp si-iws-builder-jar-with-dependencies.jar
     de.sranko_informatik.ibmi.iwsbuilder.App "/QSYS.LIB/SIIWSB.LIB/QIWSSSRC.FILE/HELLOWORLD.MBR"

How to debug IWS Builder

  1. Debug with the configuration from ifs
java -Xdebug 
     -Xrunjdwp:transport=dt_socket,address=8998,server=y 
     -cp si-iws-builder-jar-with-dependencies.jar 
     de.sranko_informatik.ibmi.iwsbuilder.App "/home/cecuser/si-iws-builder/IWSBuilder/src/main/qiwsssrc/HELLOWORLD.IWSS"
  1. Debug with the configuration from QSYS.LIB
java -Xdebug 
     -Xrunjdwp:transport=dt_socket,address=8998,server=y 
     -cp si-iws-builder-jar-with-dependencies.jar 
     de.sranko_informatik.ibmi.iwsbuilder.App "/QSYS.LIB/SIIWSB.LIB/QIWSSSRC.FILE/HELLOWORLD.MBR"
Clone this wiki locally